API Authentication Guide

SecureAI exposes a REST API that lets you build integrations, automate workflows, and connect external tools to your AI-powered workspace. Every API request must be authenticated. This guide covers how to generate API keys, use OAuth 2.0 flows, and manage tokens securely.

Authentication Methods

SecureAI supports two authentication methods:

Choose API keys for simple, trusted backend integrations. Choose OAuth 2.0 when your application acts on behalf of individual users or when you need granular permission scopes.

API Key Authentication

API keys are the simplest way to authenticate. They are long-lived credentials tied to a specific user or service account.

Generating an API Key

1. Log in to SecureAI and click your profile icon in the lower-left corner.
2. Select Settings > Account > API Keys.
3. Click Create New API Key.
4. Give the key a descriptive name (e.g., "Parts Catalog Sync", "CI Pipeline").
5. Copy the key immediately -- it will not be shown again.

Admin-generated keys: Administrators can also generate API keys from the Admin Panel > Settings > API Tokens. Admin-generated tokens can have broader permissions, including access to organization-wide endpoints.

Using an API Key

Include the key in the Authorization header of every request:

Authorization: Bearer sk-your-api-key-here

Example -- list your conversations:

curl -X GET https://your-secureai-instance.com/api/v1/chats \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json"

API Key Best Practices

• Never commit keys to source control. Store them in environment variables or a secrets manager.
• Use one key per integration. If a key is compromised, you can revoke it without disrupting other integrations.
• Name keys descriptively. When you have multiple keys, clear names make it easy to identify which integration uses which key.
• Rotate keys periodically. Even without a known compromise, rotating keys every 90 days limits exposure from undetected leaks.
• Revoke unused keys. If an integration is decommissioned, revoke its key immediately from the API Keys settings page.

Revoking an API Key

1. Go to Settings > Account > API Keys.
2. Find the key by name.
3. Click Revoke. The key stops working immediately.

Revoking a key cannot be undone. Any integration using that key will start receiving 401 Unauthorized responses.

OAuth 2.0 Authentication

OAuth 2.0 is the standard protocol for delegated authorization. Use it when your application needs to act on behalf of a SecureAI user without handling their password.

How OAuth Works in SecureAI

1. Your application redirects the user to SecureAI's authorization page.
2. The user logs in and approves the permissions your application is requesting.
3. SecureAI redirects back to your application with an authorization code.
4. Your application exchanges the code for an access token and a refresh token.
5. Your application uses the access token to make API calls on the user's behalf.

Registering an OAuth Application

Before you can use OAuth, an administrator must register your application:

1. Log in as an administrator.
2. Go to Admin Panel > Settings > OAuth Applications.
3. Click Add Application.
4. Fill in the required fields:
   • Application Name -- a human-readable name shown to users during authorization.
   • Redirect URI -- the URL where SecureAI sends the authorization code after the user approves. Must use HTTPS in production.
   • Scopes -- the permissions your application needs (see "Scopes" below).
5. Save the application. You will receive a Client ID and Client Secret.

Keep the Client Secret confidential. Treat it like a password. Never expose it in client-side code or public repositories.

Authorization Code Flow

This is the recommended flow for server-side applications.

Step 1: Redirect the user to authorize

GET https://your-secureai-instance.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.com/callback
  &scope=chat:read chat:write
  &state=random-csrf-token

The state parameter is required. Generate a random, unguessable string and verify it when the callback returns. This prevents CSRF attacks.

Step 2: User approves the request

SecureAI shows the user a consent screen listing the requested scopes. If the user approves, SecureAI redirects to your redirect_uri:

https://your-app.com/callback?code=AUTH_CODE_HERE&state=random-csrf-token

Step 3: Exchange the code for tokens

curl -X POST https://your-secureai-instance.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_HERE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://your-app.com/callback"

Response:

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

Step 4: Use the access token

curl -X GET https://your-secureai-instance.com/api/v1/chats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Scopes

Scopes limit what an OAuth application can do. Request only the scopes your application actually needs.

Admin scopes are only granted to applications registered by administrators and authorized by admin users.

Token Management

Access Token Lifetime

Access tokens expire after 1 hour (3600 seconds) by default. Your administrator can configure a different expiration in the admin panel.

When an access token expires, API calls return 401 Unauthorized. Your application must refresh the token or prompt the user to re-authorize.

Refreshing Tokens

Use the refresh token to get a new access token without requiring the user to log in again:

curl -X POST https://your-secureai-instance.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=rt-a1b2c3d4e5f6..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...(new)",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt-x7y8z9w0...(new)"
}

Note that the response includes a new refresh token. Always store the latest refresh token -- previous ones are invalidated after use (refresh token rotation).

Handling Token Expiration in Code

Build your integration to handle expired tokens gracefully:

1. Make the API call.
2. If you receive a 401 response, use the refresh token to get a new access token.
3. Retry the original API call with the new access token.
4. If the refresh also fails (e.g., refresh token expired or revoked), redirect the user to re-authorize.

Most HTTP client libraries support interceptors or middleware that automate this pattern.

Refresh Token Lifetime

Refresh tokens expire after 30 days of inactivity by default. Each time you use a refresh token, the inactivity timer resets. If a refresh token is not used for 30 days, the user must re-authorize.

Revoking OAuth Tokens

Users can revoke an application's access from their SecureAI settings:

1. Go to Settings > Account > Connected Applications.
2. Find the application.
3. Click Revoke Access.

Administrators can revoke any user's OAuth tokens from the admin panel. Developers can also revoke tokens programmatically:

curl -X POST https://your-secureai-instance.com/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Rate Limiting

All API requests are subject to rate limits regardless of authentication method. Default limits:

When you exceed a rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Your administrator can adjust rate limits in Admin Panel > Settings > API Rate Limits. See the "API rate limiting and quotas" article for detailed configuration guidance.

Troubleshooting

401 Unauthorized

• API key: Verify the key is correct and has not been revoked. Check for extra whitespace or line breaks in the header value.
• OAuth: The access token may have expired. Use the refresh token to get a new one.
• Both: Confirm the Authorization header format is Bearer <token> (with a space after "Bearer").

403 Forbidden

The token is valid but lacks the required permissions. Check that:

• The API key was generated by a user with the necessary role (e.g., admin endpoints require an admin user's key).
• The OAuth application was granted the required scopes.

Invalid Redirect URI

During OAuth authorization, SecureAI rejects the request if the redirect_uri does not exactly match one registered for the application -- including trailing slashes and URL encoding. Verify the URI in Admin Panel > Settings > OAuth Applications.

Refresh Token Invalid

Refresh tokens become invalid when:

• The token has not been used for 30 days.
• The user revoked the application's access.
• An administrator revoked the token.
• The token was already used (refresh token rotation -- use the new token from the response).

In all cases, redirect the user to re-authorize.

Security Recommendations

• Use HTTPS for all API communication. Tokens sent over HTTP can be intercepted.
• Store tokens server-side. Never store access tokens or API keys in browser localStorage, cookies accessible to JavaScript, or mobile app source code.
• Validate the state parameter in OAuth flows to prevent CSRF attacks.
• Implement token rotation. Always use the newest refresh token from the API response.
• Log API key usage. Enable audit logging so your team can detect unauthorized access patterns.
• Restrict OAuth redirect URIs. Register only the specific callback URLs your application uses. Avoid wildcard patterns.

Automotive Aftermarket Use Cases

Common API integrations for automotive aftermarket organizations:

• Parts catalog sync -- use an API key to periodically push updated parts data into a SecureAI knowledge base.
• Shop management system integration -- use OAuth so that each service advisor's SecureAI queries are scoped to their own account and conversation history.
• Automated diagnostics pipeline -- use an API key to send diagnostic trouble codes (DTCs) to SecureAI and retrieve recommended repair procedures programmatically.
• Customer portal -- use OAuth to let customers interact with a parts lookup assistant through your own web application, with each customer authenticated individually.