authentication

Authentication Overview

The Ottimate API uses a two-layer authentication approach:

1. X-API-Key: Required for all requests to identify your application
2. OAuth2 Bearer Token: Required for accessing user-specific resources

How to send your first request

1. API Key

During early access, your Ottimate Partner Manager will issue you an API Key. Your API key determines your plan and API limits.

Important: The X-API-Key header must be included with every request to the Ottimate API.

$
curl -H "X-API-Key: your-api-key-here" \
>
     -H "Authorization: Bearer your-access-token-here" \
>
     https://api.ottimate.com/v1/resource

2. OAuth2 Authentication

Ottimate uses the OAuth2 Authorization Code flow to authenticate users and access their resources. Your Ottimate Partner Manager will provide you with:

• Client ID: Identifies your application
• Client Secret: Secret key for your application (keep this secure!)

Available Scopes

Scopes define what permissions your application is requesting from the user. Currently supported scopes:

• accounts.can_access_dashboard: Grants access to user dashboard and account information

OAuth2 Authorization Code Workflow

The Authorization Code flow is a secure method for obtaining access tokens. Here’s how it works:

Step 1: User Authorization

Redirect the user to Ottimate’s authorization endpoint in the browser:

https://auth.ottimate.com/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=accounts.can_access_dashboard&
  state=RANDOM_STATE_STRING

Parameters:

• response_type: Must be code
• client_id: Your application’s Client ID
• redirect_uri: URL where users will be redirected after authorization
• scope: Permissions your application is requesting (e.g., accounts.can_access_dashboard)
• state: Random string to prevent CSRF attacks

Step 2: User Consent

The user will be presented with a consent screen showing what permissions your application is requesting. After the user approves, they will be redirected to your redirect_uri with an authorization code:

https://your-redirect-uri.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_STRING

Step 3: Exchange Code for Tokens

Your application exchanges the authorization code for an access token and refresh token:

$
curl -X POST https://auth.ottimate.com/oauth/token \
>
  -H "Content-Type: application/x-www-form-urlencoded" \
>
  -H "X-API-Key: your-api-key-here" \
>
  -d "grant_type=authorization_code" \
>
  -d "code=AUTHORIZATION_CODE" \
>
  -d "client_id=YOUR_CLIENT_ID" \
>
  -d "client_secret=YOUR_CLIENT_SECRET" \
>
  -d "redirect_uri=YOUR_REDIRECT_URI"

Response:

1
{
2
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
4
  "token_type": "Bearer",
5
  "expires_in": 3600
6
}

Step 4: Use the Bearer Token

Include the access token in the Authorization header with the Bearer prefix for all API requests:

$
curl -H "X-API-Key: your-api-key-here" \
>
     -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
>
     https://api.ottimate.com/v1/resource

Refreshing Access Tokens

Access tokens expire after a certain period (typically 1 hour). Use the refresh token to obtain a new access token without requiring user interaction:

$
curl -X POST https://auth.ottimate.com/oauth/token \
>
  -H "Content-Type: application/x-www-form-urlencoded" \
>
  -H "X-API-Key: your-api-key-here" \
>
  -d "grant_type=refresh_token" \
>
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
>
  -d "client_id=YOUR_CLIENT_ID" \
>
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

1
{
2
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
4
  "token_type": "Bearer",
5
  "expires_in": 3600
6
}

3. Making Authenticated Requests

Every request to the Ottimate API requires both authentication headers:

$
curl -X GET https://api.ottimate.com/v1/your-endpoint \
>
  -H "X-API-Key: your-api-key-here" \
>
  -H "Authorization: Bearer your-access-token-here"

Best Practices

• Secure Storage: Never expose your Client Secret in client-side code
• Token Storage: Store access tokens and refresh tokens securely
• Token Refresh: Implement automatic token refresh before expiration
• Error Handling: Handle 401 Unauthorized responses by refreshing tokens
• State Parameter: Always use and validate the state parameter to prevent CSRF attacks