Add OAuth2.0 to your APIs

Secure your APIs in minutes with OAuth 2.0 client credentials, scoped access, and JWT validation using Scalekit

APIs are a way to let your customers, partners, and external systems interact with your application and it’s data. It requires authentication to ensure only authorized clients can consume your APIs. Scalekit provides a way to add OAuth2.0 based client credentials authentication to your API endpoints.

In should here’s how it would work:

Installation
Section titled “Installation”

Scalekit becomes the authorization server for your APIs. Using Scalekit provides necessary methods to register and authenticate API clients.
Terminal window
```
pip install scalekit-sdk-python
```
Alternatively, you can use the REST APIs directly.

Currently Scalekit supports Python SDKs, contact us if you need support for your tech stack.

Enable API client registration for your customers

Allow your customers to register their applications as API clients. This process generates unique credentials that they can use to authenticate their application when interacting with your API.

Scalekit will return a client ID and secret that you can show to your customers to integrate their application with your API.

An Organization ID identifies your customer, and multiple API clients can be registered for the same organization.
The POST /organizations/{organization_id}/clients endpoint creates a new API client for the organization. See Scalekit API Authentication to get the <SCALEKIT_ACCESS_TOKEN> in case of HTTP requests.

cURL
Python

# For authentication details, see: http://docs.scalekit.com/apis#description/authentication
curl -L '<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<ORGANIZATION_ID>/clients' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <SCALEKIT_ACCESS_TOKEN>' \
-d '{
    "name": "GitHub Actions Deployment Service",  # A descriptive name for the API client
    "description": "Service account for GitHub Actions to deploy applications to production",  # A detailed explanation of the clients purpose and usage
    "custom_claims": [  # Key-value pairs that provide additional context about the client. Each claim must have a `key` and `value` field
        {
            "key": "github_repository",
            "value": "acmecorp/inventory-service"
        },
        {
            "key": "environment",
            "value": "production_us"
        }
    ],
    "scopes": [  # List of permissions the client needs (e.g., ["deploy:applications", "read:deployments"])
        "deploy:applications",
        "read:deployments"
    ],
    "audience": [  # List of API endpoints this client will access (e.g., ["deployment-api.acmecorp.com"])
        "deployment-api.acmecorp.com"
    ],
    "expiry": 3600  # Token expiration time in seconds. Defaults to 3600 (1 hour)
}'

Sample response

{
    "client": {
        "client_id": "m2morg_68315758685323697",
        "secrets": [
            {
                "id": "sks_68315758802764209",
                "create_time": "2025-04-16T06:56:05.360Z",
                "update_time": "2025-04-16T06:56:05.367190455Z",
                "secret_suffix": "UZ0X",
                "status": "ACTIVE",
                "last_used_time": "2025-04-16T06:56:05.360Z"
            }
        ],
        "name": "GitHub Actions Deployment Service",
        "description": "Service account for GitHub Actions to deploy applications to production",
        "organization_id": "org_59615193906282635",
        "create_time": "2025-04-16T06:56:05.290Z",
        "update_time": "2025-04-16T06:56:05.292145150Z",
        "scopes": [
            "deploy:applications",
            "read:deployments"
        ],
        "audience": [
            "deployment-api.acmecorp.com"
        ],
        "custom_claims": [
            {
                "key": "github_repository",
                "value": "acmecorp/inventory-service"
            },
            {
                "key": "environment",
                "value": "production_us"
            }
        ]
    },
    "plain_secret": "test_ly8G57h0ErRJSObJI6dShkoa..."
}

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",  # A descriptive name for the API client
7
    description="Service account for GitHub Actions to deploy applications to production",  # A detailed explanation of the client's purpose and usage
8
    custom_claims=[  # Key-value pairs that provide additional context about the client. Each claim must have a `key` and `value` field
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"],  # List of permissions the client needs
19
    audience=["deployment-api.acmecorp.com"],  # List of API endpoints this client will access
20
    expiry=3600  # Token expiration time in seconds. Defaults to 3600 (1 hour)
21
)
22

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

28
# Persist the generated credentials securely in your application
29
client_id = response.client.client_id
30
plain_secret = response.plain_secret

Sample response

{
    "client": {
        "client_id": "m2morg_68315758685323697",
        "secrets": [
            {
                "id": "sks_68315758802764209",
                "create_time": "2025-04-16T06:56:05.360Z",
                "update_time": "2025-04-16T06:56:05.367190455Z",
                "secret_suffix": "UZ0X",
                "status": "ACTIVE",
                "last_used_time": "2025-04-16T06:56:05.360Z"
            }
        ],
        "name": "GitHub Actions Deployment Service",
        "description": "Service account for GitHub Actions to deploy applications to production",
        "organization_id": "org_59615193906282635",
        "create_time": "2025-04-16T06:56:05.290Z",
        "update_time": "2025-04-16T06:56:05.292145150Z",
        "scopes": [
            "deploy:applications",
            "read:deployments"
        ],
        "audience": [
            "deployment-api.acmecorp.com"
        ],
        "custom_claims": [
            {
                "key": "github_repository",
                "value": "acmecorp/inventory-service"
            },
            {
                "key": "environment",
                "value": "production_us"
            }
        ]
    },
    "plain_secret": "test_ly8G57h0ErRJSObJI6dShkoaq6bigo11Dxcf.."
}

API client requests Bearer access token for API authentication
Section titled “API client requests Bearer access token for API authentication”

API clients use the client_id and client_secret issued in the previous step to reach your Scalekit environment and get the access token. No action is needed by you in your API server. This section only demonstrates how API clients get the access_token.

The client sends a POST request to the /oauth/token endpoint:
- cURL
- Python
POST /oauth/token
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, your Scalekit environment issues a JWT access token to the API client.
Access token response
```
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. Your API server validates these tokens before granting access to resources.

Validate and authenticate API client’s access tokens

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

import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: 'YOUR_JWKS_URI',
  cache: true
});

async function getPublicKey(header: any): Promise<string> {
  return new Promise((resolve, reject) => {
    client.getSigningKey(header.kid, (err, key) => {
      if (err) reject(err);
      else resolve(key.getPublicKey());
    });
  });
}

# This is automatically handled by Scalekit SDK

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

import jwt from 'jsonwebtoken';

async function verifyToken(token: string, publicKey: string) {
  try {
    const decoded = jwt.decode(token, { complete: true });
    const verified = jwt.verify(token, publicKey, {
      algorithms: ['RS256'],
      complete: true
    });
    return verified.payload;
  } catch (error) {
    throw new Error('Token verification failed');
  }
}

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

claims = scalekit_client.validate_access_token_and_get_claims(
    token=token
)

Upon successful token verification, your API server gains confidence in the request’s legitimacy and can proceed to process the request, leveraging the authorization scopes embedded within the token.

Register API client’s scopes Optional

Scopes are embedded in the access token and validated server-side using the Scalekit SDK. This ensures that API clients only access resources they’re authorized for, adding an extra layer of security.

or example, you might create an API client for a customer’s deployment service with scopes like deploy:applications and read:deployments.

1
curl -L 'https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/organizations/<ORGANIZATION_ID>/clients' \
2
-H 'Content-Type: application/json' \
3
-H 'Authorization: Bearer <SCALEKIT_ACCESS_TOKEN>' \
4
-d '{
5
    "name": "GitHub Actions Deployment Service",
6
    "description": "Service account for GitHub Actions to deploy applications to production",
7
    "scopes": [
8
        "deploy:applications",
9
        "read:deployments"
10
    ],
11
    "expiry": 3600
12
}'

Sample response

{
    "client": {
        "client_id": "m2morg_68315758685323697",
        "secrets": [
            {
                "id": "sks_68315758802764209",
                "create_time": "2025-04-16T06:56:05.360Z",
                "update_time": "2025-04-16T06:56:05.367190455Z",
                "secret_suffix": "UZ0X",
                "status": "ACTIVE",
                "last_used_time": "2025-04-16T06:56:05.360Z"
            }
        ],
        "name": "GitHub Actions Deployment Service",
        "description": "Service account for GitHub Actions to deploy applications to production",
        "organization_id": "org_59615193906282635",
        "create_time": "2025-04-16T06:56:05.290Z",
        "update_time": "2025-04-16T06:56:05.292145150Z",
        "scopes": [
            "deploy:applications",
            "read:deployments"
        ]
    },
    "plain_secret": "test_ly8G57h0ErRJSObJI6dShkoaq6bigo11Dxcfa6reKG1kKNVbqBKW4H5Ctmb5UZ0X"
}

1
// Use case: Your customer requests API access for their deployment automation.
2
// You register an API client app with the appropriate scopes.
3
import { ScalekitClient } from '@scalekit-sdk/node';
4

5
// Initialize Scalekit client (see installation guide for setup)
6
const scalekit = new ScalekitClient(
7
  process.env.SCALEKIT_ENVIRONMENT_URL,
8
  process.env.SCALEKIT_CLIENT_ID,
9
  process.env.SCALEKIT_CLIENT_SECRET
10
);
11

12
async function createAPIClient() {
13
  try {
14
    // Define API client details with scopes your customer's app needs
15
    const clientDetails = {
16
      name: 'GitHub Actions Deployment Service',
17
      description: 'Service account for GitHub Actions to deploy applications to production',
18
      scopes: ['deploy:applications', 'read:deployments'],
19
      expiry: 3600, // Token expiry in seconds
20
    };
21

22
    // API call to register the client
23
    const response = await scalekit.m2m.createClient({
24
      organizationId: process.env.SCALEKIT_ORGANIZATION_ID,
25
      client: clientDetails,
26
    });
27

28
    // Response contains client details and the plain_secret (only returned once)
29
    const clientId = response.client.client_id;
30
    const plainSecret = response.plain_secret;
31

32
    // Provide these credentials to your customer securely
33
    console.log('Created API client:', clientId);
34
  } catch (error) {
35
    console.error('Error creating API client:', error);
36
  }
37
}
38

39
createAPIClient();

1
# Use case: Your customer requests API access for their deployment automation.
2
# You register an API client app with the appropriate scopes.
3
import os
4
from scalekit import ScalekitClient
5

6
# Initialize Scalekit client (see installation guide for setup)
7
scalekit_client = ScalekitClient(
8
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
9
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
10
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
11
)
12

13
try:
14
    # Define API client details with scopes your customer's app needs
15
    from scalekit.v1.clients.clients_pb2 import OrganizationClient
16

17
    client_details = OrganizationClient(
18
        name="GitHub Actions Deployment Service",
19
        description="Service account for GitHub Actions to deploy applications to production",
20
        scopes=["deploy:applications", "read:deployments"],
21
        expiry=3600  # Token expiry in seconds
22
    )
23

24
    # API call to register the client
25
    response = scalekit_client.m2m_client.create_organization_client(
26
        organization_id=os.getenv("SCALEKIT_ORGANIZATION_ID"),
27
        m2m_client=client_details
28
    )
29

30
    # Response contains client details and the plain_secret (only returned once)
31
    client_id = response.client.client_id
32
    plain_secret = response.plain_secret
33

34
    # Provide these credentials to your customer securely
35
    print("Created API client:", client_id)
36

37
except Exception as e:
38
    print("Error creating API client:", e)

The API returns a JSON object with two key parts:

client.client_id - The client identifier
plain_secret - The client secret (only returned once, never stored by Scalekit)

Provide both values to your customer securely. Your customer will use these credentials in their application to authenticate with your API. The plain_secret is never shown again after creation.

Verify API client’s scopes

When your API server receives a request from an API client app, you must validate the scopes present in the access token provided in the Authorization header. The access token is a JSON Web Token (JWT).

First, let’s look at the claims inside a decoded JWT payload. Scalekit encodes the granted scopes in the scopes field.

{
  "client_id": "m2morg_69038819013296423",
  "exp": 1745305340,
  "iat": 1745218940,
  "iss": "<SCALEKIT_ENVIRONMENT_URL>",
  "jti": "tkn_69041163914445100",
  "nbf": 1745218940,
  "oid": "org_59615193906282635",
  "scopes": [
    "deploy:applications",
    "read:deployments"
  ],
  "sub": "m2morg_69038819013296423"
}

Your API server should inspect the scopes array in the token payload to authorize the requested operation. Here’s how you validate the token and check for a specific scope in your API server.

Node.js
Python


27 collapsed lines
1
// Security: ALWAYS validate the access token on your server before trusting its claims.
2
// This prevents token forgery and ensures the token has not expired.
3
import { ScalekitClient } from '@scalekit-sdk/node';
4
import jwt from 'jsonwebtoken';
5
import jwksClient from 'jwks-rsa';
6

7
const scalekit = new ScalekitClient(
8
  process.env.SCALEKIT_ENVIRONMENT_URL,
9
  process.env.SCALEKIT_CLIENT_ID,
10
  process.env.SCALEKIT_CLIENT_SECRET
11
);
12

13
// Setup JWKS client for token verification
14
const client = jwksClient({
15
  jwksUri: `${process.env.SCALEKIT_ENVIRONMENT_URL}/.well-known/jwks.json`,
16
  cache: true
17
});
18

19
async function getPublicKey(header) {
20
  return new Promise((resolve, reject) => {
21
    client.getSigningKey(header.kid, (err, key) => {
22
      if (err) reject(err);
23
      else resolve(key.getPublicKey());
24
    });
25
  });
26
}
27

28
async function checkPermissions(req, res, next) {
29
  const authHeader = req.headers.authorization;
30
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
31
    return res.status(401).send('Unauthorized: Missing token');
32
  }
33
  const token = authHeader.split(' ')[1];
34

35
  try {
36
    // Decode to get the header with kid
37
    const decoded = jwt.decode(token, { complete: true });
38
    const publicKey = await getPublicKey(decoded.header);
39

40
    // Verify the token signature and claims
41
    const verified = jwt.verify(token, publicKey, {
42
      algorithms: ['RS256'],
43
      complete: true
44
    });
45

46
    const decodedToken = verified.payload;
47

48
    // Check if the API client app has the required scope
49
    const requiredScope = 'deploy:applications';
50
    if (decodedToken.scopes && decodedToken.scopes.includes(requiredScope)) {
51
      // API client app has the required scope, proceed with the request
52
      next();
53
    } else {
54
      // API client app does not have the required scope
55
      res.status(403).send('Forbidden: Insufficient permissions');
56
    }
57
  } catch (error) {
58
    // Token is invalid or expired
59
    res.status(401).send('Unauthorized: Invalid token');
60
  }
61
}


14 collapsed lines
1
# Security: ALWAYS validate the access token on your server before trusting its claims.
2
# This prevents token forgery and ensures the token has not expired.
3
import os
4
import functools
5
from scalekit import ScalekitClient
6
from flask import request, jsonify
7

8
# Initialize Scalekit client
9
scalekit_client = ScalekitClient(
10
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
11
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
12
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
13
)
14

15
def check_permissions(required_scope):
16
    def decorator(f):
17
        @functools.wraps(f)
18
        def decorated_function(*args, **kwargs):
19
            auth_header = request.headers.get('Authorization')
20
            if not auth_header or not auth_header.startswith('Bearer '):
21
                return jsonify({"error": "Unauthorized: Missing token"}), 401
22

23
            token = auth_header.split(' ')[1]
24

25
            try:
26
                # Validate the token using the Scalekit SDK
27
                claims = scalekit_client.validate_access_token_and_get_claims(token=token)
28

29
                # Check if the API client app has the required scope
30
                if required_scope in claims.get('scopes', []):
31
                    # API client app has the required scope
32
                    return f(*args, **kwargs)
33
                else:
34
                    # API client app does not have the required scope
35
                    return jsonify({"error": "Forbidden: Insufficient permissions"}), 403
36
            except Exception as e:
37
                # Token is invalid or expired
38
                return jsonify({"error": "Unauthorized: Invalid token"}), 401
39
        return decorated_function
40
    return decorator
41

42
# Example usage in a Flask route
43
# @app.route('/deploy', methods=['POST'])
44
# @check_permissions('deploy:applications')
45
# def deploy_application():
46
#     return jsonify({"message": "Deployment successful"})

Add OAuth2.0 to your APIs

Installation

Enable API client registration for your customers

API client requests Bearer access token for API authentication

Validate and authenticate API client’s access tokens

Register API client’s scopes Optional

Verify API client’s scopes