# Authorization

KORE's APIs are secured using the [`OAuth2.0`](https://datatracker.ietf.org/doc/html/rfc6749) Protocol, specifically [`Client Credentials`](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) Flow to obtain tokens to authorize you to access your resources.

To call any of KORE's APIs, you will need to exchange your **Client Credentials**, `Client ID` and `Client Secret`, for an `Access Token`. You can view your Client Credentials in your Client's Details.

## How it Works

<figure><img src="https://documents.lucid.app/documents/d6444a1e-ada2-4804-8ae0-8579cbe2ae30/pages/0_0?a=937&#x26;x=406&#x26;y=-177&#x26;w=1048&#x26;h=795&#x26;store=1&#x26;accept=image%2F*&#x26;auth=LCA%209030a4868e8ba4b5e54828623a4b707202d8ad2b476930e077dab2fc583b9369-ts%3D1707845991" alt=""><figcaption></figcaption></figure>

### 1. Send API Credentials

Your application sends the client credentials, Client ID and Client Secret, to KORE's authorization server.&#x20;

{% hint style="info" %}
KORE's auth endpoint is `https://api.korewireless.com/api-services/v1/auth/token`
{% endhint %}

{% code title="Request" lineNumbers="true" %}

```
curl -X POST https://api.korewireless.com/api-services/v1/auth/token  \
  --header 'cache-control: no-cache'  \
  --header 'content-type: application/x-www-form-urlencoded'  \
  --data "grant_type=client_credentials" \
  --data "client_id=$KORE_CLIENT_ID" \
  --data "client_secret=$KORE_CLIENT_SECRET"
```

{% endcode %}

### 2. KORE validates the credentials

If the Client Credentials are not valid, you will receive an error.

{% code title="Error: HTTP 401" lineNumbers="true" %}

```json
{
    "error": "unauthorized_client",
    "error_description": "Invalid client or Invalid client credentials"
}
```

{% endcode %}

If the credentials are valid, KORE responds with an access token per [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-4.2.2).&#x20;

{% hint style="info" %}
The `expires_in` property is given in seconds.
{% endhint %}

{% tabs %}
{% tab title="Response Schema" %}
{% code lineNumbers="true" %}

```json
{
   "access_token": "ACCESS_TOKEN",
   "expires_in": "EXPIRY_TIME",
   "token_type": "Bearer",
   "scope": "YOUR_SCOPE"
}
```

{% endcode %}
{% endtab %}

{% tab title="Sample Response" %}

```json
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyYUZlaTNFc1Y1WGh5Ui1YT1JTX0VmNzFuaVFpVWZJejhVcXNfRlg1VXBrIn0.eyJleHAiOjE3MTUxMzc1MjUsImlhdCI6MTcxNTEzMzkyNSwianRpIjoiZWJmMTEyODItZjZkMC00MGYxLWIyZTktNWMzMTNhMjlhYzJkIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay5kZXYubmdpbnguazFkLms4LmNpbi5rb3JlLmtvcmV3aXJlbGVzcy5jb20vcmVhbG1zL0tPUkUtQ0lEUCIsImF1ZCI6ImFwaS1ndyIsInN1YiI6Ijc0NjYzZTE3LTY2ZTQtNGU0Mi1hNThiLWUyYjdlNTIyN2ViZSIsInR5cCI6IkJlYXJlciIsImF6cCI6ImtjXzAxaHhhejRzZTJlaDZyMzZxZ3B0cWFodzFkIiwic2NvcGUiOiJlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SG9zdCI6IjEwLjIzMy42OS4wIiwiaXAtcmFuZ2UiOltdLCJhcGkta2V5IjoibzJnWUZON3EwMGNraG05dnl4aXVrNDVURi9TU1VHS0lZdEhMUDJTU0dSb2tKZGNDUC9hUTV4dFlRNFVac2JEd0hlbk82Ry96ZFFqSGpIYWM1Tmp2T0I0bFZyYkpRUndsNEtacU1jZE84TDVXcWc9PSIsImFjY291bnQtaWQiOiJDTzE2ODY3MjZxdW56b3J4MzU2MjgwIiwiY2xpZW50LXR5cGUiOiJhZG1pbiIsInNjb3BlcyI6eyJnbG9iYWxSZXNvdXJjZXMiOlt7InJlc291cmNlTmFtZSI6IkFQSSBDbGllbnRzIiwiYWNjZXNzIjpbIlJlYWQiLCJXcml0ZSIsIk1vZGlmeSIsIkRlbGV0ZSJdfV19LCJjbGllbnRBZGRyZXNzIjoiMTAuMjMzLjY5LjAiLCJjbGllbnQtb3duZXIiOiJqYmVuQGtvcmV3aXJlbGVzcy5jb20iLCJjbGllbnRfaWQiOiJrY18wMWh4YXo0c2UyZWg2cjM2cWdwdHFhaHcxZCIsInR3aWxpby1zaWQiOiJkZXZwb3J0YWxTSUR0ZXN0In0.Ih07y9-6hqUaFRnBB2wTeep56PWA57BA0amrxQ55VDQAOxXFmgygimsVznkMVHcm0BtUQEf07dPmMuPQSHCqb6KVFpDg9RGWWG_R7BX6BFA0BaiMkQu93uhbYxJEpomYfDhzUWpxYmbEk1SouQT7cSd1_y39wvHdxHWGqPYhav1GuCmKLhSu0V3-TT6to257yH1s7c3NmQQkeaIUA4R55WxqQxWcIRN_fhYlHdxeVJ7Djsjrfn_Ne_hex2y4fLBGAA-QU7T1oPm0XAazmI1FVtg7kytFy5S-aXBRoYtkJwq0Es",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "email"
}
```

{% endtab %}
{% endtabs %}

### 3. Make an API Call

When you call any REST API, include the access token (returned from step[#id-2.-kore-validates-the-credentials](#id-2.-kore-validates-the-credentials "mention")) in the authorization header: `--header Authorization: Bearer {access_token}`.&#x20;

When your access token expires, repeat the process, starting with Step 1.

Refer to our [guide on Refreshing your API Access token](https://docs.korewireless.com/developers/how-to/apis/refresh-api-access-token) for an example.

## Client Credentials

When you create an API Client, the `Client Secret` is shown only once, after which you will not be able to retrieve the `Client Secret`.

The `Client ID` is always shown as this is how you uniquely identify your client.

{% hint style="warning" %}
Your client credentials are like your username and password and should be secured appropriately.
{% endhint %}

## Access Token Expiry Times

When you create your API Client, you can pick an expiry time.&#x20;

The options we support are

* 1 hour
* 1 day (24 hours)
* 30 days
* 24 months (2 years)

When you request an `Access Token`, given your Client Credentials, the `Acces Token` you will have an expiration time based on what you selected when creating your API Client. When your `Access Token` expires, you will be required to request a new access token.&#x20;

If the `Access Token` expires, and your application attempts to make an API call, you will be presented with an error.

{% code title="Error: HTTP 403" lineNumbers="true" %}

```json
{
    "message": "User is not authorized to access this resource with an explicit deny",
    "error": "Invalid or expired token"
}
```

{% endcode %}

## Access Token Scopes

[Access Token Scope](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) is a mechanism in OAuth2.0 that limits your application to only the products and resources you require.&#x20;

Picking your scopes is done during client creation, which can be modified later.

{% hint style="warning" %}
Changing the scope of your API Client requires you to generate a new Access Token, as the Access Token you are currently using will have the old scopes.
{% endhint %}

When you receive your token from KORE, it will contain the scopes you identified when you created your API Client.