Authentication

This guide explains how to authenticate with the Uptinio API. The API supports two authentication methods depending on your use case.

Authentication Methods

The Uptinio API supports two types of authentication:

User Authentication Tokens - For frontend applications and user-specific operations
Project API Tokens - For infrastructure monitoring and project-based operations

User Authentication Tokens

User authentication tokens are used for frontend applications (like React) and user-specific API operations. These tokens are obtained by logging in with user credentials.

Getting a User Authentication Token

Step 1: Register a User (if needed)

You can register a new user in two ways:

Option A: Standard Registration (Name, Email, Password)

bash

POST /api/v1/users
Content-Type: application/json

{
  "user": {
    "email": "user@example.com",
    "name": "John Doe",
    "password": "secure_password123",
    "password_confirmation": "secure_password123",
    "first_website": "https://example.com"
  }
}

Example with curl:

bash

curl -X POST "https://app.uptinio.com/api/v1/users" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "email": "user@example.com",
      "name": "John Doe",
      "password": "secure_password123",
      "password_confirmation": "secure_password123",
      "first_website": "https://example.com"
    }
  }'

Response:

json

{
  "message": "User created successfully",
  "user": {
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Request Fields:

Field	Type	Required	Description
email	string	Yes	User's email address
name	string	Yes	User's full name
password	string	Yes	User's password (minimum 6 characters)
password_confirmation	string	Yes	Password confirmation (must match password)
first_website	string	No	Optional URL for initial website monitoring

Option B: Quick Registration with Endpoint (Email Only)

This method creates a user with a provisional password and automatically sets up monitoring for a website:

bash

POST /api/v1/registrations
Content-Type: application/json

{
  "endpoint": "https://example.com",
  "email": "user@example.com"
}

Example with curl:

bash

curl -X POST "https://app.uptinio.com/api/v1/registrations" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://example.com",
    "email": "user@example.com"
  }'

Response:

json

{
  "message": "User registered successfully",
  "user": {
    "email": "user@example.com",
    "name": "User"
  },
  "network_monitor": {
    "uuid": "NM123456789",
    "url": "https://example.com"
  }
}

Note: With this method, a provisional password is generated and sent via email. You'll need to check your email for the password or reset it.

Registration Error Responses:

422 Unprocessable Entity - Validation errors:

json

{
  "errors": [
    "Email has already been taken",
    "Password is too short (minimum is 6 characters)",
    "Name can't be blank"
  ]
}

422 Unprocessable Entity - User already exists:

json

{
  "errors": "User already exist"
}

Step 2: Sign In

bash

POST /api/v1/auth/sign_in
Content-Type: application/json

{
  "user": {
    "email": "user@example.com",
    "password": "your_password"
  }
}

Response:

json

{
  "message": "Signed in successfully",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "User",
    "email_verified": true,
    "authentication_token": "abc123xyz..."
  }
}

Using User Authentication Tokens

Include the token in the Authorization header:

bash

curl -H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN" \
     https://app.uptinio.com/api/v1/auth/validate

JavaScript Example:

javascript

const response = await fetch('https://app.uptinio.com/api/v1/auth/validate', {
  headers: {
    'Authorization': `Bearer ${authenticationToken}`,
    'Content-Type': 'application/json'
  }
});

Endpoints Using User Authentication

User authentication tokens are used by default for most endpoints, including:

GET /api/v1/auth/validate - Validate token
DELETE /api/v1/auth/sign_out - Sign out
POST /api/v1/auth/google - Sign in with Google (exchange Google ID token for Uptinio token)
GET /api/v1/users/:id - Get user details
GET /api/v1/users/project_api_tokens - Get all projects with their API tokens
GET /api/v1/users/current_project_api_token - Get the current project's API token
And other user-specific endpoints

Token Validation

You can validate your token at any time:

bash

GET /api/v1/auth/validate
Authorization: Bearer YOUR_AUTHENTICATION_TOKEN

Valid Token Response:

json

{
  "valid": true,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "User",
    "email_verified": true
  }
}

Invalid Token Response:

json

{
  "valid": false,
  "errors": ["Invalid or expired token"]
}

Project API Tokens

Project API tokens are used for infrastructure monitoring, server metrics, and project-based operations. These tokens are generated in your Uptinio dashboard and are tied to a specific project.

Getting Your Project API Token

Log in to your Uptinio dashboard
Navigate to Settings > API Keys
Click "Generate New API Key"
Copy the key immediately (it won't be shown again)

Using Project API Tokens

Include your project API token in the Authorization header:

bash

curl -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
     https://app.uptinio.com/api/v1/network_monitors

JavaScript Example:

javascript

const response = await fetch('https://app.uptinio.com/api/v1/network_monitors', {
  headers: {
    'Authorization': `Bearer ${projectApiToken}`,
    'Content-Type': 'application/json'
  }
});

Endpoints Using Project API Tokens

Project API tokens are used for infrastructure and monitoring endpoints:

GET /api/v1/network_monitors - List monitors
POST /api/v1/network_monitors - Create monitor
GET /api/v1/incidents - List incidents
POST /api/v1/server_metrics - Submit metrics
GET /api/v1/servers - List servers
POST /api/v1/analysis - AI analysis
GET /api/v1/integrations - List integrations
GET /api/v1/accounts/usage - Usage statistics
GET /api/v1/general-status - Health check

Public Endpoints (No Authentication Required)

The following endpoints do not require authentication:

POST /api/v1/users - User registration (with name, email, and password)
POST /api/v1/registrations - Quick user registration (with endpoint monitoring)
POST /api/v1/auth/sign_in - User login

Security Best Practices

For User Authentication Tokens

Store tokens securely
- Use secure storage (localStorage, secure cookies, or secure keychain)
- Never commit tokens to version control
- Use environment variables in server-side applications
Handle token expiration
- Implement token refresh logic
- Re-authenticate when tokens expire
- Validate tokens before making requests
Protect against XSS
- Sanitize user input
- Use Content Security Policy (CSP)
- Avoid storing tokens in easily accessible locations

For Project API Tokens

Never share your API key
- Keep it secure and private
- Don't commit it to version control
- Use environment variables
Rotate keys regularly
- Generate new keys periodically
- Revoke old keys when no longer needed
Use different keys for different purposes
- Separate keys for development and production
- Different keys for different applications or services
Limit key scope
- Use project-specific tokens when possible
- Revoke keys immediately if compromised

Rate Limiting

Both authentication methods are subject to rate limiting:

Standard plans: 100 requests per minute
Enterprise plans: 1000 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Remaining requests in current window
X-RateLimit-Reset - Time when the rate limit resets

Error Responses

Invalid or Missing Token

Status: 401 Unauthorized

json

{
  "errors": ["Invalid or expired token"]
}

json

{
  "errors": ["Missing authentication token"]
}

Invalid Project API Token

Status: 401 Unauthorized

json

{
  "error": "Unauthorized"
}

Banned User

Status: 401 Unauthorized or 403 Forbidden

json

{
  "errors": ["Invalid or expired token"]
}

Rate Limit Exceeded

Status: 429 Too Many Requests

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests"
  }
}

Email Verification

Email verification is required for users who sign up with email and password. After registration, users receive a 6-digit verification code via email. Once verified, users can create network monitors and integrations.

Note: Users who sign in with Google OAuth are automatically verified and don't need to verify their email.

Verify Email Address

Verify your email address using the verification code sent to your email.

http

POST /api/v1/email_verifications/verify
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST "https://app.uptinio.com/api/v1/email_verifications/verify" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

JavaScript Example:

javascript

const response = await fetch('https://app.uptinio.com/api/v1/email_verifications/verify', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${authenticationToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: '123456'
  })
});

const data = await response.json();
if (data.success) {
  console.log('Email verified!');
}

Request Body

Field	Type	Required	Description
code	string	Yes	The 6-digit verification code sent to your email

Response

Success (200 OK) - Email verified:

json

{
  "success": true,
  "message": "Email verified successfully",
  "user": {
    "email": "user@example.com",
    "email_verified": true
  }
}

Success (200 OK) - Already verified:

json

{
  "success": true,
  "message": "Email is already verified",
  "user": {
    "email": "user@example.com",
    "email_verified": true
  }
}

Error Responses:

400 Bad Request - Missing verification code:

json

{
  "success": false,
  "error": "code_required",
  "message": "Verification code is required"
}

422 Unprocessable Entity - Invalid or expired code:

json

{
  "success": false,
  "error": "invalid_or_expired_code",
  "message": "Invalid or expired verification code. Please request a new code."
}

Resend Verification Code

Request a new verification code if you didn't receive it or if it expired.

http

POST /api/v1/email_verifications/resend
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST "https://app.uptinio.com/api/v1/email_verifications/resend" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json"

JavaScript Example:

javascript

const response = await fetch('https://app.uptinio.com/api/v1/email_verifications/resend', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${authenticationToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
if (data.success) {
  console.log('New verification code sent!');
}

Response

Success (200 OK):

json

{
  "success": true,
  "message": "Verification code sent successfully",
  "user": {
    "email": "user@example.com",
    "email_verified": false
  }
}

Success (200 OK) - Already verified:

json

{
  "success": true,
  "message": "Email is already verified",
  "user": {
    "email": "user@example.com",
    "email_verified": true
  }
}

Error Responses:

429 Too Many Requests - Resend too soon:

json

{
  "success": false,
  "error": "resend_too_soon",
  "message": "Please wait 45 seconds before requesting a new code",
  "seconds_until_can_resend": 45
}

500 Internal Server Error - Failed to send:

json

{
  "success": false,
  "error": "send_failed",
  "message": "Failed to send verification code. Please try again later."
}

Verification Code Details

Verification codes are 6 digits (e.g., 123456)
Codes expire after 15 minutes
You can request a new code after 1 minute from the last request
Codes are sent to the email address associated with your account
Once verified, you can create network monitors and integrations

Why Email Verification is Required

Email verification is required to:

Create network monitors
Create integrations
Ensure account security
Prevent spam and abuse

Note: If you sign in with Google OAuth, your email is automatically verified and you can skip this step.

POST /api/v1/users - Register a new user (verification code is sent automatically)
POST /api/v1/auth/sign_in - Sign in to get authentication token
Monitor API Reference - Create monitors (requires verified email)
Integrations API Reference - Create integrations (requires verified email)

CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) for frontend applications. All API v1 endpoints accept requests from any origin with the following headers:

Authorization - For authentication tokens
Content-Type - For request body type
Accept - For response format

Preflight requests (OPTIONS) are automatically handled.

Authentication ​

Authentication Methods ​

User Authentication Tokens ​

Getting a User Authentication Token ​

Using User Authentication Tokens ​

Endpoints Using User Authentication ​

Token Validation ​

Project API Tokens ​

Getting Your Project API Token ​

Using Project API Tokens ​

Endpoints Using Project API Tokens ​

Public Endpoints (No Authentication Required) ​

Security Best Practices ​

For User Authentication Tokens ​

For Project API Tokens ​

Rate Limiting ​

Error Responses ​

Invalid or Missing Token ​

Invalid Project API Token ​

Banned User ​

Rate Limit Exceeded ​

Email Verification ​

Verify Email Address ​

Request Body ​

Response ​

Resend Verification Code ​

Response ​

Verification Code Details ​

Why Email Verification is Required ​

Related Endpoints ​

CORS Configuration ​

Next Steps ​

Authentication

Authentication Methods

User Authentication Tokens

Getting a User Authentication Token

Using User Authentication Tokens

Endpoints Using User Authentication

Token Validation

Project API Tokens

Getting Your Project API Token

Using Project API Tokens

Endpoints Using Project API Tokens

Public Endpoints (No Authentication Required)

Security Best Practices

For User Authentication Tokens

For Project API Tokens

Rate Limiting

Error Responses

Invalid or Missing Token

Invalid Project API Token

Banned User

Rate Limit Exceeded

Email Verification

Verify Email Address

Request Body

Response

Resend Verification Code

Response

Verification Code Details

Why Email Verification is Required

Related Endpoints

CORS Configuration

Next Steps