> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://catena.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server.

# Authentication API Overview

The Authentication API provides OAuth 2.0 endpoints for obtaining and managing access tokens required for all Catena API requests.

> **Check**
>
> **Industry Standard:** OAuth 2.0 provides secure, token-based authentication using the Client Credentials grant type for server-to-server integrations.

---

## Available Endpoints

#### Token Generation

Exchange your Client ID and Secret for an access token to authorize API requests.

#### Token Revocation

Revoke access tokens and refresh tokens when they're no longer needed or have been compromised.

---

## How It Works

#### Request Token

Call the token endpoint with your Client ID and Secret to receive an access token.

#### Use Token

Include the token in the `Authorization: Bearer <token>` header for all API requests.

#### Refresh or Revoke

Request a new token before expiry or revoke tokens when no longer needed.

> **Info**
>
> **Getting Credentials:** Contact [support@catenaclearing.io](mailto:support@catenaclearing.io) to receive your Client ID and Secret for API access.

---

## Authentication Flow

```mermaid
sequenceDiagram
    participant App as Your Application
    participant Auth as Auth Server
    participant API as Catena API

    App->>Auth: POST /token (client_id, client_secret)
    Auth->>App: access_token (expires_in: 3600s)
    App->>API: GET /v2/telematics/vehicles (Bearer token)
    API->>App: 200 OK (vehicle data)

    Note over App,Auth: Token expires after 3600s

    App->>Auth: POST /token (refresh)
    Auth->>App: new access_token
```

---

## Token Management Best Practices

#### Cache Tokens

Store access tokens in memory and reuse them until they expire. Don't request a new token for every API call—this wastes resources and may trigger rate limits.

#### Handle Expiration Gracefully

Check the `expires_in` value in the token response and refresh proactively before expiration. Alternatively, handle `401 Unauthorized` responses by requesting a new token and retrying.

#### Use Environment Variables

Store Client ID and Secret in environment variables or secure credential management systems—never hardcode them in source code.

#### Implement Token Refresh Logic

Build automatic token refresh logic into your application to maintain uninterrupted API access.

#### Monitor for Unauthorized Responses

Log and alert on `401 Unauthorized` responses to detect authentication issues or credential problems early.

---

# Ready to Get Started?

#### [Quick Start Guide](/get-started/quickstart)

Get up and running in 10 minutes with our step-by-step integration tutorial.

#### [API Reference](/api-reference)

Explore all available endpoints, parameters, and response formats.

#### [Get API Credentials](/get-started/getting-access)

Request access to start building with the Catena Telematics API.

#### [Supported Providers](/get-started/supported-providers)

Browse the telematics providers available through our platform.