# 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](/developers/how-to/apis/refresh-api-access-token.md) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.korewireless.com/developers/api-management/auth.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.