# Get started

All requests to the Younium API must be authenticated using a **JWT access token**. This guide explains how to generate the required credentials, acquire a JWT token, and use it to make authenticated API calls.

## Step 1: Generate an API Token and Client Credentials

<br>

1. Open the **User Profile Menu** in the top-right corner (click your user name).
2. Go to **Privacy & Security**.\ <br>

   <div align="left"><figure><img src="https://940708998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMV73ftGLs1NaypiZYzZB%2Fuploads%2Fgit-blob-78d07ccb59e1c26b9f696fa21c6dc1e7eb963ed1%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure></div>

   \ <br>
3. Select **Personal Tokens** in the left-hand panel.
4. Click **Generate Token**.\
   \ <br>

   <div align="left"><figure><img src="https://940708998-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMV73ftGLs1NaypiZYzZB%2Fuploads%2Fgit-blob-381f3d5b632277e64c132b3006d292b6a4e0b497%2Fimage%20(1).png?alt=media" alt=""><figcaption></figcaption></figure></div>

   <br>
5. Enter a descriptive name for the token and click **Create**.
6. The **Client ID** and **Secret Key** will now be displayed.
   * ⚠️ **Important**: Copy these values immediately. They will not be visible again.
   * You will use them to generate the JWT token.\ <br>

<div align="left"><img src="https://younium.gitbook.io/~gitbook/image?url=https%3A%2F%2F940708998-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMV73ftGLs1NaypiZYzZB%252Fuploads%252FfXHKaqA8o7bEJ3l5Uk5u%252FCredentials%2520%281%29.png%3Falt%3Dmedia%26token%3Dc0361a08-2e62-4130-926a-81c2cbeabc61&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=a51723c7&#x26;sv=1" alt=""></div>

## Step 2: Generate a JWT Token <a href="#generating-a-jwt-token" id="generating-a-jwt-token"></a>

Make a `POST` request to the `/auth/v2/token` endpoint with your client credentials.\
This guide uses the latest auth endpoint version (v2). Guide to v1 can be found [here](https://developer.younium.com/get-started-1).

#### Endpoints

* Production: `https://api.younium.com/auth/v2/token`
* Sandbox: `https://api.sandbox.younium.com/auth/v2/token`
* US Production: `https://api.us.younium.com/auth/v2/token`
* US Sandbox: `https://api.sandbox.us.younium.com/auth/v2/token`

#### Request Header

```http
Content-Type: application/json
```

#### Request Body

```json
{ 
  "clientId": "<Client ID>", 
  "secret": "<Secret Key>" 
}
```

#### Successful Response

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cC...",
  "refresh_token": "4baf4774-5ef9-4983-a8d8-f4fdae7f7000",
  "expires_in": 86400,
  "expires": "Thu, 27 Sep 2025 11:12:01 GMT" 
}
```

* The **access token** is valid for **24 hours**.
* Once expired, you must request a new token.

#### Error Response

In case of authentication failure , you may receive an error response:

```json
{
    errors: ["<Error message>"]
}
```

* `400` or `401`: Invalid credentials or other authentication issues.

## Step 3: Making Authenticated API Calls

Include the access token in the request headers:

```http
Authorization: Bearer <JWT Token>
Content-Type: application/json
api-version: <version>   // optional but recommended
legal-entity: <Entity ID or Name>
```

#### Notes

* **`legal-entity`**:
  * Required if your tenant has multiple legal entities.
  * If invalid, the request returns `403 Forbidden`.
* **`api-version`**:
  * Default is **2.1**.
  * Explicitly setting the version is recommended.

***

### Common Authentication Errors

* **401 Unauthorized**
  * Token missing, expired, or invalid.
* **403 Forbidden**
  * The request is authenticated, but access is blocked. Possible reasons:
    * Invalid or missing `legal-entity` header.
    * Insufficient user permissions.
    * Restricted access to integrations or services.