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

# Authentication

> Learn how to authenticate API requests using access tokens obtained through the OAuth 2.0 flow.

## Making Authenticated Requests

Include the access token in the Authorization header of your API requests:

```bash theme={null}
curl -X GET "https://app.useorbitcrm.ai/api/v1/forms" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

## Token Expiration

> [!WARNING]
>
> **Access tokens expire after 1 hour.** Use the refresh token to obtain a new access token without requiring the user to re-authorize.

To refresh an expired access token:

```bash theme={null}
curl -X POST "https://app.useorbitcrm.ai/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"
```

The response has the same shape as the first token response, including `team_id`, with a **new refresh token**: refresh tokens rotate on every use. Replace the stored pair as soon as the response arrives. The old refresh token keeps working for 60 seconds after its first use (so a retry of a request that timed out still succeeds); after that, using it again answers `400 invalid_grant` and the person has to authorize again. Refresh tokens expire 30 days after they are issued, so an app that refreshes at least monthly never loses its connection.

## Authentication Errors

| Status | Error | Solution |
| - | - | - |
| `401` | `invalid_token` | Token is expired or invalid. Refresh the token. |
| `401` | `token_expired` | Use your refresh token to get a new access token. |
| `403` | `insufficient_scope` | Request additional scopes from the user. |
| `429` | `rate_limit_exceeded` | Too many requests. Wait for `Retry-After` and back off. |

## Best Practices

> [card] Store tokens securely
>
> Never expose tokens in client-side code or logs.

> [card] Proactively refresh
>
> Refresh tokens before they expire to avoid interruptions.

> [card] Handle errors gracefully
>
> Implement proper error handling for auth failures.

## Next Steps

> [card] [App Permissions](https://docs.useorbitcrm.ai/apps/permissions.md)
>
> Learn about available scopes

> [card] [API Reference](https://docs.useorbitcrm.ai/developers/api/overview.md)
>
> Make your first API call


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