> For the complete documentation index, see [llms.txt](https://legisratio.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://legisratio.gitbook.io/docs/graphql-api/api-authentication.md).

# API Authentication

{% hint style="info" %}
All API requests require authentication using **Bearer tokens** in the `Authorization` header.
{% endhint %}

We support two ways to authenticate:

1. **OAuth 2.0 (Recommended)**: Use your Client ID and Client Secret to dynamically generate access tokens.
2. **Static API Tokens**: For simple integrations or legacy support.

***

## OAuth 2.0 Authentication

The new system uses **OAuth 2.0 Client Credentials Flow**. This is the most secure and scalable way to authenticate.

### 1. Register a New Client (API Key)

If you need to programmatically generate a new set of API keys (Client ID and Client Secret) for your applications or customers, use the registration endpoint.

{% hint style="warning" %}
You need a **Master Token** provided by LegisRatio to register new clients. Please note that Master Tokens are only available to users with a **Plus subscription**.
{% endhint %}

{% code overflow="wrap" %}

```bash
curl -X POST https://api-oauth.legisratio.com/oauth/register \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer <MASTER_TOKEN>' \
  -d '{
    "client_name": "Your Application Name",
    "numberOfLicences": 5
  }'
```

{% endcode %}

The response will contain your `client_id`, `client_secret`, and `registration_access_token`. **Store these securely.**

### 2. Generate an Access Token

Exchange your `client_id` and `client_secret` for a short-lived **Access Token**.

{% code overflow="wrap" %}

```bash
curl -X POST https://api-oauth.legisratio.com/oauth/token \
  -u "<client_id>:<client_secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=graphql:read"
```

{% endcode %}

**Response:**

```json
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer"
}
```

### 3. Use the Access Token

Include the token in the `Authorization` header of your GraphQL requests.

{% code overflow="wrap" %}

```bash
curl -X POST \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ laws { id title } }"}' \
  https://api.legisratio.com/graphql
```

{% endcode %}

***

## Client Management

You can perform administrative tasks on your clients using the `registration_access_token` provided during registration.

* **Discovery**: `GET https://api-oauth.legisratio.com/.well-known/openid-configuration`
* **Get Client Info**: `GET /oauth/clients/:client_id` (Requires Registration Token)
* **Update Licences**: `PATCH /oauth/clients/:client_id/licences` (Requires Registration Token)
* **Revoke Client**: `DELETE /oauth/clients/:client_id` (Requires Registration Token)

***

## Static API Token (Legacy)

If you have been provided with a static API token by our team, use it directly as follows:

{% code overflow="wrap" %}

```bash
POST /graphql
Host: api.legisratio.com
Authorization: Bearer YOUR_STATIC_TOKEN_HERE
Content-Type: application/json

{
  "query": "query { laws { id title } }"
}
```

{% endcode %}

{% hint style="success" %}
**Migrating to OAuth** We recommend all new integrations use the OAuth 2.0 system. If you wish to migrate from static tokens and have a **Plus subscription**, please create an account at [apps.legisratio.com](https://apps.legisratio.com/) to request your Master Token.
{% endhint %}