> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitforms.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://orbitforms.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.
</Warning>

To refresh an expired access token:

```bash theme={null}
curl -X POST "https://orbitforms.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"
```

## 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_limited`       | Too many requests. Implement exponential backoff. |

## Best Practices

<CardGroup cols={1}>
  <Card title="Store tokens securely" icon="lock">
    Never expose tokens in client-side code or logs.
  </Card>

  <Card title="Proactively refresh" icon="clock">
    Refresh tokens before they expire to avoid interruptions.
  </Card>

  <Card title="Handle errors gracefully" icon="shield">
    Implement proper error handling for auth failures.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="App Permissions" icon="key" href="/apps/permissions">
    Learn about available scopes
  </Card>

  <Card title="API Reference" icon="shield" href="/developers/api/overview">
    Make your first API call
  </Card>
</CardGroup>