Skip to content
Rime Documentation

API Authentication

All API requests require a valid bearer token in the Authorization header. This page explains how to obtain tokens, how they expire and refresh, and how to use them in your requests.

Obtaining a token

Email and password

If your account uses email/password authentication, obtain a token by sending a POST request to the login endpoint:

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


{
  "email": "[email protected]",
  "password": "your-password"
}

A successful response returns an access token and a refresh token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The expires_in value is in seconds. The default access token lifetime is 1 hour (3600 seconds).

SSO (SAML or OIDC)

If your organization uses SSO, the login flow is browser-based. Programmatic access via SSO requires completing the SSO flow and extracting the resulting token:

  1. Open the SSO login URL in a browser or headless client:

    GET /api/v1/auth/sso/{provider_id}/login

    This redirects to your identity provider (Azure AD, Okta, etc.).

  2. Complete authentication with your identity provider.

  3. The callback redirects back to Rime with an authorization code. Rime exchanges the code for tokens and returns them in the response.

For automated scripts and CI/CD pipelines, we recommend using an API key (available in Project > Settings > API Keys) rather than SSO tokens, since SSO requires a browser interaction.

Google OAuth

For accounts using Google OAuth:

  1. Start the flow: 
    GET /api/v1/auth/google/login
  2. Complete Google authentication in the browser.
  3. The callback returns tokens in the same format as email/password login.

Using tokens in requests

Include the access token in the Authorization header of every API request:

GET /api/v1/connectors
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

Do not include the token in query parameters or the request body. The Authorization header is the only supported method.

Token expiry

Access tokens expire after 1 hour by default. When a token expires, the API returns a 401 Unauthorized response:

{
  "error": {
    "code": "unauthorized",
    "message": "Token has expired."
  }
}

Your client should detect 401 responses and use the refresh token to obtain a new access token (see below) rather than prompting the user to log in again.

Token refresh

Use the refresh token to obtain a new access token without re-authenticating:

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


{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

A successful response returns a new access token and a new refresh token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Important details about refresh tokens:

  • Refresh tokens are single-use. Each refresh request returns a new refresh token and invalidates the previous one. Always store the latest refresh token.
  • Refresh tokens expire after 30 days. If the refresh token expires, the user must log in again.
  • Refresh token rotation prevents replay attacks. If a refresh token is used twice (indicating it was intercepted), all tokens for that session are revoked.

Token storage

For web applications, Rime’s frontend stores tokens in memory (not localStorage or cookies) to minimize exposure to XSS attacks. If you are building a custom integration:

  • Server-side applications: Store tokens in encrypted storage or environment variables. Never commit tokens to source control.
  • Client-side applications: Store tokens in memory. Use the refresh flow to obtain new tokens when the application restarts.
  • CI/CD pipelines: Use API keys (see below) rather than user tokens.

API keys

For automated scripts, CI/CD pipelines, and service-to-service integrations, use API keys instead of user tokens. API keys do not expire (unless revoked) and are not tied to a user session.

To create an API key:

  1. Go to Project > Settings > API Keys
  2. Click Create API Key
  3. Give the key a name that describes its purpose (e.g., “CI pipeline”, “Monitoring integration”)
  4. Select the permissions for the key (read-only, read-write, or admin)
  5. Copy the key immediately — it is shown only once

Use the API key as a Bearer token in the same way as an access token:

Authorization: Bearer rime_key_abc123...

API keys are scoped to a project. They cannot access other projects in your tenant.

To revoke an API key, go to Project > Settings > API Keys, find the key, and click Revoke. Revocation is immediate — any in-flight requests using the key will fail.

Permissions

Tokens inherit the permissions of the user who created them. If a user has read-only access to a project, their token can only perform read operations.

API keys have their own permission level, set at creation time:

Permission levelCapabilities
Read-onlyList and view all resources, read monitoring data
Read-writeEverything in read-only, plus create, update, and delete resources
AdminEverything in read-write, plus manage users, API keys, and project settings

Security recommendations

  • Rotate API keys periodically, especially for long-lived integrations.
  • Use the most restrictive permission level that meets your needs.
  • Monitor API key usage in the audit log to detect unauthorized access.
  • Revoke tokens and keys immediately if you suspect they have been compromised.

Next steps