Get started

Discover how to authenticate to Youniums APIs

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

1. Open the User Profile Menu in the top-right corner (click your user name).

2. Go to Privacy & Security.

   

3. Select Personal Tokens in the left-hand panel.

4. Click Generate Token.

   

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.

Step 2: Generate a JWT Token

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.

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

Content-Type: application/json

Request Body

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

Successful Response

{
  "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:

{
    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:

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.