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

# Authentication

> Learn how to authenticate with the ReadingSteps API.

# Authentication

The ReadingSteps API uses OAuth 2.0 for authentication. All API requests require a valid access token.

## Getting Started

### 1. Create an API Key

Visit the [Developer Portal](https://developers.readingsteps.uk) to create your API key.

### 2. Choose Your Authentication Method

We support two authentication methods:

* **OAuth 2.0 Authorization Code Flow** (recommended for web apps)
* **API Key** (recommended for server-to-server applications)

## OAuth 2.0 Authorization Code Flow

### Step 1: Redirect to Authorization URL

```
https://auth.readingsteps.uk/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read+write&
  state=RANDOM_STRING
```

### Step 2: Exchange Code for Access Token

```bash theme={null}
POST https://auth.readingsteps.uk/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET
```

### Response

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read write"
}
```

## API Key Authentication

For server-to-server applications, use your API key in the request header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.readingsteps.uk/v1/users/me
```

## Token Refresh

Access tokens expire after 1 hour. Use your refresh token to get a new one:

```bash theme={null}
POST https://auth.readingsteps.uk/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET
```

## Scopes

Available OAuth scopes:

| Scope   | Description                               |
| ------- | ----------------------------------------- |
| `read`  | Read access to user data                  |
| `write` | Write access to user data                 |
| `admin` | Administrative access (requires approval) |

## Error Handling

### Common Errors

| Error Code        | Description                                 |
| ----------------- | ------------------------------------------- |
| `invalid_request` | The request is missing a required parameter |
| `invalid_client`  | Client authentication failed                |
| `invalid_grant`   | The provided authorization code is invalid  |
| `invalid_scope`   | The requested scope is invalid              |

### Example Error Response

```json theme={null}
{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired"
}
```

## Best Practices

* Store tokens securely (never in client-side code)
* Use HTTPS for all API calls
* Implement token refresh logic
* Revoke unused tokens
* Monitor token usage for suspicious activity