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

# Authentication

> How to authenticate your requests to the Sunbird AI API

The Sunbird AI API uses **Bearer Token** authentication. You must include a valid access token in the `Authorization` header of your HTTP requests.

## Overview

1. **Register** an account.
2. **Login** to obtain an access token.
3. **Include** the token in your requests.

## Registration

To start using the API, you need to create an account. You have two options:

* **Web:** Sign up at [https://api.sunbird.ai/register](https://api.sunbird.ai/register), then grab your access token / API key from the [tokens page](https://api.sunbird.ai/keys).
* **API:** Register programmatically via the `/auth/register` endpoint.

<Note>
  You will need a valid email address.
</Note>

```bash theme={null}
curl -X POST "https://api.sunbird.ai/auth/register" \
     -H "Content-Type: application/json" \
     -d '{
           "email": "user@example.com",
           "password": "securePassword123",
           "username": "user123"
         }'
```

## Getting an Access Token

After registering, exchange your credentials for an access token using the `/auth/token` endpoint. Note that this endpoint expects **form-encoded** data, not JSON.

```bash theme={null}
curl -X POST "https://api.sunbird.ai/auth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=user@example.com&password=securePassword123"
```

The response will include your token:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

## Using the Token

Include the token in the `Authorization` header of your requests:

```http theme={null}
Authorization: Bearer <your_access_token>
```

### Example Request

<CodeGroup>
  ```python Python theme={null}
  import requests

  headers = {
      "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
  response = requests.get("https://api.sunbird.ai/auth/me", headers=headers)
  ```

  ```javascript JavaScript theme={null}
  fetch('https://api.sunbird.ai/auth/me', {
    headers: {
      'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    }
  });
  ```
</CodeGroup>

## Token Lifetime

Access tokens **do not expire**. Your token effectively acts as your **API key** — use the same token to authenticate every request to the Sunbird AI API. Generate it once (from the [tokens page](https://api.sunbird.ai/keys) or the `/auth/token` endpoint), store it securely, and reuse it.

If a request returns a `401 Unauthorized` error, the token is missing or invalid — double-check that it is included correctly in the `Authorization` header.

## Security Best Practices

<Warning>
  Never commit your API tokens or passwords to version control (like GitHub).
</Warning>

* **Environment Variables**: Store your tokens in environment variables (e.g., `SUNBIRD_API_TOKEN`).
* **Backend Proxy**: If you are building a frontend application, route requests through your own backend to keep your credentials hidden. Do not expose your token in client-side code.

## OAuth Integration

We support Google OAuth for easier login. This is primarily handled via our web interface, but the underlying flow uses standard OAuth 2.0 protocols.

## Common Errors

| Status Code | Error        | Description                                         |
| :---------- | :----------- | :-------------------------------------------------- |
| `401`       | Unauthorized | The token is missing, invalid, or expired.          |
| `403`       | Forbidden    | You do not have permission to access this resource. |