API Authentication quickstart

Add secure authentication to your APIs

Learn how to add authentication to your APIs in minutes. This guide shows you how to:

Register API clients that need to access your services
Set up OAuth 2.0 authentication using client credentials
Validate access tokens to ensure only authorized clients can call your APIs

Who is this for? This guide is for developers who want to secure their APIs and control which external systems can access them.

Prerequisites:

A Scalekit account (sign up here if you don’t have one)
Basic understanding of REST APIs
Familiarity with OAuth 2.0 (optional)

npm install @scalekit-sdk/node

pip install scalekit-sdk-python

go get -u github.com/scalekit-inc/scalekit-sdk-go

/* Gradle users - add the following to your dependencies in build file */
implementation "com.scalekit:scalekit-sdk-java:1.1.3"

<!-- Maven users - add the following to your `pom.xml` -->
<dependency>
    <groupId>com.scalekit</groupId>
    <artifactId>scalekit-sdk-java</artifactId>
    <version>1.1.3</version>
</dependency>

Register an API client

Before an application can access your API, you need to register it as a client. This creates secure credentials that the app developers will use to authenticate its API requests.

When you register a client, you’ll receive a unique client ID and secret - similar to a username and password for applications. Present it to your API client developers to use in their code.

cURL
Python

1
# For authentication details, see: http://docs.scalekit.com/apis#description/authentication
2
curl -L 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<ORGANIZATION_ID>/clients' \
3
-H 'Content-Type: application/json' \
4
-H 'Authorization: Bearer <SCALEKIT_ACCESS_TOKEN>' \
5
-d '{
6
    "name": "GitHub Actions Deployment Service",
7
    "description": "Service account for GitHub Actions to deploy applications to production",
8
    "custom_claims": [
9
        {
10
            "key": "github_repository",
11
            "value": "acmecorp/inventory-service"
12
        },
13
        {
14
            "key": "environment",
15
            "value": "production_us"
16
        }
17
    ],
18
    "scopes": [
19
        "deploy:applications",
20
        "read:deployments"
21
    ],
22
    "audience": [
23
        "deployment-api.acmecorp.com"
24
    ],
25
    "expiry": 3600
26
}'

1
from scalekit.v1.clients.clients_pb2 import OrganizationClient
2

3
org_id = "<SCALEKIT_ORGANIZATION_ID>"
4

5
api_client = OrganizationClient(
6
    name="GitHub Actions Deployment Service",
7
    description="Service account for GitHub Actions to deploy applications to production",
8
    custom_claims=[
9
        {
10
            "key": "github_repository",
11
            "value": "acmecorp/inventory-service"
12
        },
13
        {
14
            "key": "environment",
15
            "value": "production_us"
16
        }
17
    ],
18
    scopes=["deploy:applications", "read:deployments"],
19
    audience=["deployment-api.acmecorp.com"],
20
    expiry=3600
21
)
22

23
response = scalekit_client.m2m_client.create_organization_client(
24
    organization_id=org_id,
25
    m2m_client=api_client
26
)

API client registration parameters

Parameter	Type	Description
name	string	A descriptive name for the API client (e.g., “GitHub Actions Deployment Service”)
description	string	A detailed explanation of the client’s purpose and usage
custom_claims	array	Key-value pairs that provide additional context about the client. Each claim must have a `key` and `value` field
scopes	array	List of permissions the client needs (e.g., [“deploy:applications”, “read:deployments”])
audience	array	List of API endpoints this client will access (e.g., [“deployment-api.acmecorp.com”])
expiry	number	Token expiration time in seconds. Defaults to 3600 (1 hour)

The API response contains the client details, including the client_id and client_secret.

1
{
2
    "client": {
3
        "client_id": "m2morg_68315758685323697",
4
        "secrets": [
5
            {
6
                "id": "sks_68315758802764209",
7
                "create_time": "2025-04-16T06:56:05.360Z",
8
                "update_time": "2025-04-16T06:56:05.367190455Z",
9
                "secret_suffix": "UZ0X",
10
                "status": "ACTIVE",
11
                "last_used_time": "2025-04-16T06:56:05.360Z"
12
            }
13
        ],
14
        "name": "GitHub Actions Deployment Service",
15
        "description": "Service account for GitHub Actions to deploy applications to production",
16
        "organization_id": "org_59615193906282635",
17
        "create_time": "2025-04-16T06:56:05.290Z",
18
        "update_time": "2025-04-16T06:56:05.292145150Z",
19
        "scopes": [
20
            "deploy:applications",
21
            "read:deployments"
22
        ],
23
        "audience": [
24
            "deployment-api.acmecorp.com"
25
        ],
26
        "custom_claims": [
27
            {
28
                "key": "github_repository",
29
                "value": "acmecorp/inventory-service"
30
            },
31
            {
32
                "key": "environment",
33
                "value": "production_us"
34
            }
35
        ]
36
    },
37
    "plain_secret": "test_ly8G57h0ErRJSObJI6dShkoaq6bigo11Dxcfa6reKG1kKNVbqBKW4H5Ctmb5UZ0X"
38
}

Authenticate the API client

After registration, the API client authenticates with your Scalekit environment using its client_id and client_secret (the plain_secret obtained earlier) to request an access token. This process uses the OAuth 2.0 client credentials grant type.

The client sends a POST request to the /oauth/token endpoint:

cURL
Python

1
curl -X POST \
2
  "https://<SCALEKIT_ENVIRONMENT_URL>/oauth/token" \
3
  -H "Content-Type: application/x-www-form-urlencoded" \
4
  -d "grant_type=client_credentials" \
5
  -d "client_id=<API_CLIENT_ID>" \
6
  -d "client_secret=<API_CLIENT_SECRET>" \

1
client_id = "API_CLIENT_ID"
2
client_secret = "API_CLIENT_SECRET"
3

4
token_response = scalekit_client.generate_client_token(
5
    client_id=client_id,
6
    client_secret=client_secret
7
)

Upon successful authentication, Scalekit issues a JWT access token.

1
{
2
  "access_token":"<API_CLIENT_JWT_ACCESS_TOKEN>",
3
  "token_type":"Bearer",
4
  "expires_in":86399,
5
  // Same scopes that were granted during client registration
6
  "scope":"deploy:applications read:deployments"
7
}

The client includes this access token in the Authorization header of subsequent requests to your API server.

Validate access tokens in your API server

Your API server must validate the incoming JWT access token to ensure the request originates from a trusted API client and that the token is legitimate.

Validate the token in two steps:

Retrieve the public key: Fetch the appropriate public key from your Scalekit environment’s JSON Web Key Set (JWKS) endpoint. Use the kid (Key ID) from the JWT header to identify the correct key. Cache the key according to standard JWKS practices.

Node.js
Python

1
import jwksClient from 'jwks-rsa';
2

3
const client = jwksClient({
4
jwksUri: 'YOUR_JWKS_URI',
5
cache: true
6
});
7

8
async function getPublicKey(header: any): Promise<string> {
9
return new Promise((resolve, reject) => {
10
    client.getSigningKey(header.kid, (err, key) => {
11
    if (err) reject(err);
12
    else resolve(key.getPublicKey());
13
    });
14
});
15
}

1
# This is automatically handled by Scalekit SDK
2
token = token_response["<API_CLIENT_JWT_ACCESS_TOKEN>"]
3

4
claims = scalekit_client.validate_access_token_and_get_claims(
5
    token=token
6
)

Verify the token signature: Use the retrieved public key and a JWT library to verify the token’s signature and claims (like issuer, audience, and expiration).

Node.js
Python

1
import jwt from 'jsonwebtoken';
2

3
async function verifyToken(token: string, publicKey: string) {
4
try {
5
    const decoded = jwt.decode(token, { complete: true });
6
    const verified = jwt.verify(token, publicKey, {
7
    algorithms: ['RS256'],
8
    complete: true
9
    });
10
    return verified.payload;
11
} catch (error) {
12
    throw new Error('Token verification failed');
13
}
14
}

1
# Token from the incoming API request's authorization header
2
token = token_response["<API_CLIENT_JWT_ACCESS_TOKEN>"]
3

4
claims = scalekit_client.validate_access_token_and_get_claims(
5
    token=token
6
)

Find complete code examples in the Scalekit M2M Gists repository.

If the token verification succeeds, your API server can trust the request’s authenticity and proceed with processing it based on the permissions (scopes) encoded within the token.