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

# Authentication

You can authenticate to the Light API using [API keys](#api-keys) or [OAuth 2.0](#oauth-2-0) user flow.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Make sure your HTTP client follows redirects and forward the `Authorization` header, as some endpoints may redirect to other URLs.

## API Keys

To create an API key, log in into Light, navigate to "Settings" > "API Keys" and click on "Create Key". Make sure to copy and securely store the generated API key, as it will not be shown again.

Light API keys are linked to roles the same way user accounts are. The roles assigned to the API key determine what actions the key can perform.

To use API keys for authentication, include the `Authorization` header in your requests using `Basic` Authentication scheme:

```
Authorization: Basic YOUR_API_KEY
```

## OAuth 2.0

<Note>Contact Light support at [help@light.inc](mailto:help@light.inc) to setup your account for OAuth 2.0 flow</Note>

Once your account is set up, you should receive a `client_id` and `client_secret`. You will also need to provide Light with a redirect URI where users will be sent after they authorize your application.

To initiate the OAuth 2.0 authorization code flow, open the the following URL:

```
https://api.light.inc/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
```

You can also include an optional `state` parameter to this request. Check out the [OAuth 2.0 spec](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1) for more details on using the `state` parameter.

### Exchanging Authorization Code for Access Token

After the user authorizes your application, they will be redirected back to your specified redirect URI with an authorization code. You can exchange this authorization code for an access token by making a POST request to the token endpoint:

```shell theme={null}
curl -X POST https://api.light.inc/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
```

The response will include an `access_token` field, which you can use to authenticate your API requests. Include the access token in the `Authorization` header using the `Bearer` scheme:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

The response will also include a `refresh_token` field and `expires_in` field, which you can use to obtain a new access token when the current one expires.

Make sure to securely store the `access_token`, `refresh_token` and `expires_in` values so you can refresh the access token when needed.

### Refreshing Access Tokens

When your access token expires, you can obtain a new one using the refresh token. Make a POST request to the token endpoint with the following parameters:

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

The response will include a **new** `access_token`, `refresh_token`, and `expires_in` field. Use the new access token for subsequent API requests.

<Warning>Ensure you update your stored refresh token with the new one provided in the response, as the old one will be invalidated after use</Warning>