> ## Documentation Index
> Fetch the complete documentation index at: https://stage-docs.oktivo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Understand the two authentication methods: JWT and API tokens

# Authentication

Oktivo uses two authentication methods depending on the context:

| Method | Use Case | Format |
| - | - | - |
| **JWT** | Dashboard sessions, token management | `Authorization: Bearer <jwt>` |
| **API Token** | CRM integrations, programmatic calls | `Authorization: Bearer okt_...` |

## API Tokens

API tokens are designed for server-to-server integrations. They authenticate requests to the CRM API endpoints (`/api/v1/crm/calls/*`).

### Token Format

All API tokens use the `okt_` prefix followed by a random string:

```
okt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

The prefix makes tokens easy to identify in logs and secret scanners.

### Creating a Token

**From the dashboard:** open **Settings → API Tokens** (`app.oktivo.com/account`),
click **Create Token**, name it, and pick an expiry. The panel lists each token
with its expiry and last-used date, and lets you rotate (↻) or delete (🗑) it.
Each account can hold a maximum of **5 active tokens** — delete an unused one to
free a slot.

**Via the API:**

```bash theme={null}
curl -X POST https://client-backend.oktivo.com/api/v1/crm/tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "salesforce-integration",
    "expiresInDays": 90
  }'
```

> [!WARNING]
>
> The plaintext token is returned **exactly once** in the response. Store it securely you cannot retrieve it again.

### Token Expiry

Tokens expire after the configured `expiresInDays` (1–365 days). Expired tokens are automatically rejected. Plan to rotate tokens before they expire to avoid service interruptions.

### Token Rotation

Rotate a token to invalidate the old value and get a new one in a single operation:

```bash theme={null}
curl -X POST https://client-backend.oktivo.com/api/v1/crm/tokens/{tokenId}/rotate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

This returns a new plaintext token. The old token stops working immediately.

### Using API Tokens

Include the token in the `Authorization` header for all CRM API requests:

```
Authorization: Bearer okt_your_token_here
```

### Token Limits

* Maximum name length: 128 characters
* Expiry range: 1–365 days
* Tokens can be soft-deleted (they stop working immediately but records are retained)

## JWT Authentication

JWT tokens are issued when users log in through the Oktivo dashboard. They authenticate:

* Token management endpoints (`/api/v1/crm/tokens/*`)
* Webhook management endpoints (`/webhooks/endpoints/*`)
* Dashboard API calls

JWTs are managed automatically by the dashboard you don't need to handle them for CRM integrations.

## Which Should I Use?

* **Building a CRM integration?** → Use an API token
* **Managing tokens or webhooks programmatically?** → Use JWT from an authenticated session
* **Using the dashboard?** → JWT is handled automatically


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.