Machine-to-Machine Auth: API-to-API authentication patterns and client credentials flows for service-to-service communication --- # DOCUMENT BOUNDARY --- # Machine-2-Machine authentication > Secure interactions between software systems with M2M authentication, enabling secure API access for AI agents, apps, and automated workflows Machine-2-Machine (M2M) authentication secures API access for non-human clients like AI agents, third-party integrations, backend services, and automated workflows. When you need to give these machine clients secure access to your APIs, M2M authentication provides credential-based authentication using client IDs and secrets, without exposing hardcoded tokens or requiring human interaction. Your machine clients can act on behalf of an organization, a specific user, or operate independently to perform system-level tasks. You get centralized management of all machine identities with granular permissions and seamless credential rotation across internal and external services. This approach ensures your machine clients authenticate with the same rigour as human users, giving you secure, scoped access to APIs while simplifying integration development and meeting enterprise security standards. ## When to use M2M authentication [Section titled “When to use M2M authentication”](#when-to-use-m2m-authentication) You’ll use M2M auth when your APIs need to be accessed by: * Automated clients or AI agents making requests on behalf of users or organizations * External platforms or third-party integrations (like Zapier, CRM systems, analytics platforms, or payment providers) * Internal services or background jobs that programmatically invoke your APIs * Scheduled services that automatically sync data with your API * Automated workflows that update external systems In all these cases, there’s no human user session involved. The system still needs a secure way to authenticate the client and determine what access it should have. ## Understanding the OAuth 2.0 client credentials flow [Section titled “Understanding the OAuth 2.0 client credentials flow”](#understanding-the-oauth-20-client-credentials-flow) M2M authentication uses the OAuth 2.0 client credentials flow. This is the standard way for non-human clients to obtain access tokens without requiring user interaction. OAuth 2.0 is an authorization framework that allows client applications to access protected resources on a resource server by presenting an access token. The protocol delegates authorization decisions to a central authorization server, which issues access tokens after validating the client or user. The protocol defines several grant types for different use cases: * **Client credentials flow** - Use this when one system (like an automated client or AI agent) wants to access another system’s API * **Authorization code flow** - Use this when a user authorizes a machine client to act on their behalf For org-level or internal service clients, you use a `client_id` and `client_secret` to authenticate. For user-backed clients, the user first authorizes the client via the authorization code flow. ## Choose your client type [Section titled “Choose your client type”](#choose-your-client-type) Scalekit provides three types of machine clients based on the OAuth 2.0 flow: * **Org-level clients:** Use these when your automated client needs to access APIs on behalf of an organization. Tokens are scoped to a specific org (`oid`) and work well for org-wide workflows. Read the M2M authentication quickstart to set up an org-level client. * **User-level clients:** Use these when your machine client acts on behalf of a specific user. These tokens include a `uid` (user ID) in addition to `oid`, letting you enforce user-contextual access. *(Coming soon)* * **Internal service clients:** Use these for secure service-to-service communication between internal systems. These clients issue tokens with an `aud` (audience) claim to enforce destination-specific access. They’re ideal for microservices that need to communicate without org or user context. *(Coming soon)*  ## How the authentication flow works [Section titled “How the authentication flow works”](#how-the-authentication-flow-works) Here’s the complete M2M authentication flow: 1. **Register a machine client** You create an M2M client in Scalekit for the machine that needs access to your APIs. 2. **Generate credentials** Scalekit issues a `client_id` and `client_secret` for that client. Your client uses these credentials to request access tokens. 3. **Request an access token** Your client requests an access token from Scalekit’s `/oauth/token` endpoint. For org-level access, it uses the client credentials flow directly. For user-level access, it exchanges an authorization code after user consent in the authorization code flow. 4. **Receive a signed JWT** Scalekit validates the request and returns a short-lived, signed JWT that contains claims specific to your client type: * Which organization it belongs to (`oid`) * Which user it belongs to (`uid`) * What it’s allowed to do (`scopes`) * How long it’s valid for (`exp`, `nbf`) * Which service it’s intended for (`aud`) Each token is signed by Scalekit so your API can validate it locally without calling back to Scalekit. This improves performance and keeps your authorization flow resilient even if the auth server is briefly unavailable. 5. **Make authenticated API calls** Your machine client sends this token in the `Authorization` header when calling your API. 6. **Validate the token** Your API checks the token’s signature and claims locally. You don’t need to make a network call to Scalekit for validation. This approach gives you secure, programmatic authentication using short-lived, scoped tokens that you can revoke or rotate as needed. ## What Scalekit handles for you [Section titled “What Scalekit handles for you”](#what-scalekit-handles-for-you) Building secure M2M authentication from scratch can be complex when dealing with token scoping, TTL management, credential rotation, and validation. Scalekit handles these concerns out of the box with minimal setup. With just a few API calls or dashboard actions, you can: * Register machine clients scoped to an organization, user, or service * Generate and manage credentials with safe rotation * Issue signed, short-lived JWTs with the right claims (`oid`, `uid`, `aud`, `scopes`) based on the client type * Validate tokens locally in your API without calling back to Scalekit You can enforce least-privilege access for machine clients without implementing the OAuth flow or token lifecycle yourself. ## Token security and management [Section titled “Token security and management”](#token-security-and-management) * **Short-lived**: All tokens have a configurable TTL (default: 1 hour; minimum: 5 minutes) to reduce long-term risk. * **Locally verifiable**: Tokens are signed JWTs that your API can verify without calling back to Scalekit. * **Supports rotation**: Each client can store up to five secrets at a time, making credential rotation seamless with no downtime. * **Includes identity context**: Tokens contain claims like `oid` (org ID), `uid` (user ID), and `aud` (audience) so you can enforce precise access. * **Scoped access**: You define fine-grained scopes to limit what each client is allowed to do. These defaults ensure that your tokens are short-lived, constrained in what they can do, and fully verifiable without external dependencies. ## Key benefits [Section titled “Key benefits”](#key-benefits) When you implement M2M authentication with Scalekit, you get: * **Security**: You eliminate the need to share user credentials between services or expose hardcoded secrets * **Auditability**: Each service has its own identity, making it easier for you to track and audit API usage * **Scalability**: You can easily add or remove services without affecting other parts of your system * **Granular Control**: You can implement fine-grained access control at the service level To start integrating M2M authentication in your application, head to the [quickstart guide](/authenticate/m2m/api-auth-quickstart) for setting up an org-level client. --- # DOCUMENT BOUNDARY --- # Add OAuth 2.0 to your APIs > Secure your APIs in minutes with OAuth 2.0 client credentials, scoped access, and JWT validation using Scalekit APIs let your customers, partners, and external systems interact with your application and its data. You need authentication to ensure only authorized clients can consume your APIs. Scalekit helps you add OAuth 2.0-based client-credentials authentication to your API endpoints. If you are new to JWT-based API authentication, read the cookbook **[M2M JWT verification with JWKS and OAuth scopes](/cookbooks/m2m-jwks-and-oauth-scopes/)** for foundational context before following the steps below. Here’s how it works: 1. ## Installation [Section titled “Installation”](#installation) Scalekit becomes the authorization server for your APIs. Using Scalekit provides necessary methods to register and authenticate API clients. ```sh pip install scalekit-sdk-python ``` Alternatively, you can use the [REST APIs directly](/apis/#tag/api-auth). 2. ## Enable API client registration for your customers [Section titled “Enable API client registration for your customers”](#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](/apis/#description/quickstart) to get the `` in case of HTTP requests. - cURL POST /organizations/{organization\_id}/clients ```bash # For authentication details, see: http://docs.scalekit.com/apis#description/authentication curl -L '/api/v1/organizations//clients' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -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) }' ``` - Python ```python 1 from scalekit.v1.clients.clients_pb2 import OrganizationClient 2 3 org_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 ``` 3. ## API client requests Bearer access token for API authentication [Section titled “API client requests Bearer access token for API authentication”](#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 POST /oauth/token ```sh 1 curl -X POST \ 2 "https:///oauth/token" \ 3 -H "Content-Type: application/x-www-form-urlencoded" \ 4 -d "grant_type=client_credentials" \ 5 -d "client_id=" \ 6 -d "client_secret=" \ ``` * Python ```python 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 ```json 1 { 2 "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. 4. ## Validate and authenticate API client’s access tokens [Section titled “Validate and authenticate API client’s access tokens”](#validate-and-authenticate-api-clients-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: 1. **Retrieve the public key:** Fetch the appropriate public key from your Scalekit environment’s [JSON Web Key Set (JWKS)](/cookbooks/m2m-jwks-and-oauth-scopes/#jwks-and-scalekit-keys) at `https:///keys`. Use the `kid` (Key ID) from the JWT header to identify the correct key. Cache the key according to standard JWKS practices. * Node.js ```js import jwksClient from 'jwks-rsa'; const client = jwksClient({ jwksUri: `${process.env.SCALEKIT_ENVIRONMENT_URL}/keys`, cache: true }); async function getPublicKey(header: any): Promise { return new Promise((resolve, reject) => { client.getSigningKey(header.kid, (err, key) => { if (err) reject(err); else resolve(key.getPublicKey()); }); }); } ``` * Python ```py # This is automatically handled by Scalekit SDK ``` 2. **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 ```js 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'); } } ``` * Python ```py # Token from the incoming API request's authorization header token = token_response[""] 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. 5. ## Register API client’s scopes Optional [Section titled “Register API client’s scopes ”](#register-api-clients-scopes-) [OAuth scopes](/cookbooks/m2m-jwks-and-oauth-scopes/#oauth-scopes-for-machine-clients) 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. For example, you might create an API client for a customer’s deployment service with scopes like `deploy:applications` and `read:deployments`. * cURL Register an API client with specific scopes ```bash 1 curl -L 'https:///api/v1/organizations//clients' \ 2 -H 'Content-Type: application/json' \ 3 -H 'Authorization: Bearer ' \ 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 }' ``` * Node.js Register an API client with specific scopes ```javascript 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(); ``` * Python Register an API client with specific scopes ```python 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. 6. ## Verify API client’s scopes [Section titled “Verify API client’s scopes”](#verify-api-clients-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. Example decoded access token ```json { "client_id": "m2morg_69038819013296423", "exp": 1745305340, "iat": 1745218940, "iss": "", "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 Example Express.js middleware for scope validation ```javascript 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}/keys`, 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 } ``` * Python Example Flask decorator for scope validation ```python 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"}) ``` --- # DOCUMENT BOUNDARY --- # API keys > Issue long-lived, revocable API keys scoped to organizations and users for programmatic access to your APIs When your customers integrate with your APIs — whether for CI/CD pipelines, partner integrations, or internal tooling — they need a straightforward way to authenticate. Scalekit API keys give you long-lived, revocable bearer credentials for organization-level or user-level access to your APIs. In this guide, you’ll learn how to create, validate, list, and revoke API keys using the Scalekit. 1. ## Install the SDK [Section titled “Install the SDK”](#install-the-sdk) * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` Initialize the Scalekit client with your environment credentials: * Node.js Express.js ```javascript 1 import { ScalekitClient } from '@scalekit-sdk/node'; 2 3 const scalekit = new ScalekitClient( 4 process.env.SCALEKIT_ENVIRONMENT_URL, 5 process.env.SCALEKIT_CLIENT_ID, 6 process.env.SCALEKIT_CLIENT_SECRET 7 ); ``` * Python Flask ```python 1 import os 2 from scalekit import ScalekitClient 3 4 scalekit_client = ScalekitClient( 5 env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"], 6 client_id=os.environ["SCALEKIT_CLIENT_ID"], 7 client_secret=os.environ["SCALEKIT_CLIENT_SECRET"], 8 ) ``` * Go Gin ```go 1 import scalekit "github.com/scalekit-inc/scalekit-sdk-go/v2" 2 3 scalekitClient := scalekit.NewScalekitClient( 4 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 5 os.Getenv("SCALEKIT_CLIENT_ID"), 6 os.Getenv("SCALEKIT_CLIENT_SECRET"), 7 ) ``` * Java Spring Boot ```java 1 import com.scalekit.ScalekitClient; 2 3 ScalekitClient scalekitClient = new ScalekitClient( 4 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 5 System.getenv("SCALEKIT_CLIENT_ID"), 6 System.getenv("SCALEKIT_CLIENT_SECRET") 7 ); ``` 2. ## Create a token [Section titled “Create a token”](#create-a-token) To get started, create an API key scoped to an organization. You can optionally scope it to a specific user and attach custom metadata. ### Organization-scoped API key [Section titled “Organization-scoped API key”](#organization-scoped-api-key) **When to use**: Organization-scoped keys are for customers who need full access to all resources within their workspace or account. When they authenticate with the key, Scalekit validates it and confirms the organization context — your API then exposes all resources they own. **Example scenario**: You’re building a CRM like HubSpot. Your customer integrates with your API using an organization-scoped key. When they request contacts, tasks, or deals, the key validates successfully for their organization, and your API returns all resources in that workspace. This is the most common pattern for service-to-service integrations where the API key represents access on behalf of an entire organization. * Node.js ```javascript 1 try { 2 const response = await scalekit.token.createToken(organizationId, { 3 description: 'CI/CD pipeline token', 4 }); 5 6 // Store securely — this value cannot be retrieved again after creation 7 const opaqueToken = response.token; 8 // Stable identifier for management operations (format: apit_xxxxx) 9 const tokenId = response.tokenId; 10 } catch (error) { 11 console.error('Failed to create token:', error.message); 12 } ``` * Python ```python 1 try: 2 response = scalekit_client.tokens.create_token( 3 organization_id=organization_id, 4 description="CI/CD pipeline token", 5 ) 6 7 opaque_token = response.token # store this securely 8 token_id = response.token_id # format: apit_xxxxx 9 except Exception as e: 10 print(f"Failed to create token: {e}") ``` * Go ```go 1 response, err := scalekitClient.Token().CreateToken( 2 ctx, organizationId, scalekit.CreateTokenOptions{ 3 Description: "CI/CD pipeline token", 4 }, 5 ) 6 if err != nil { 7 log.Printf("Failed to create token: %v", err) 8 return 9 } 10 11 // Store securely — this value cannot be retrieved again after creation 12 opaqueToken := response.Token 13 // Stable identifier for management operations (format: apit_xxxxx) 14 tokenId := response.TokenId ``` * Java ```java 1 import com.scalekit.grpc.scalekit.v1.tokens.CreateTokenResponse; 2 3 try { 4 CreateTokenResponse response = scalekitClient.tokens().create(organizationId); 5 6 // Store securely — this value cannot be retrieved again after creation 7 String opaqueToken = response.getToken(); 8 // Stable identifier for management operations (format: apit_xxxxx) 9 String tokenId = response.getTokenId(); 10 } catch (Exception e) { 11 System.err.println("Failed to create token: " + e.getMessage()); 12 } ``` ### User-scoped API key [Section titled “User-scoped API key”](#user-scoped-api-key) **When to use**: User-scoped keys enable fine-grained data filtering based on who owns the key. Your API validates the key, receives the user context, and then exposes only data relevant to that user — enabling role-based filtering without additional database lookups. **Example scenario**: Your CRM has a `/tasks` endpoint. One customer gives their team member a user-scoped API key. When that person calls `/tasks`, the key validates for their organization *and* user, and your API returns only tasks assigned to them — not all tasks in the workspace. Another team member with a different key sees only their own tasks. User-scoped keys enable personal access tokens, per-user audit trails, and user-level rate limiting. You can also attach custom claims as key-value metadata. * Node.js ```javascript 1 try { 2 const userToken = await scalekit.token.createToken(organizationId, { 3 userId: 'usr_12345', 4 customClaims: { 5 team: 'engineering', 6 environment: 'production', 7 }, 8 description: 'Deployment service token', 9 }); 10 11 const opaqueToken = userToken.token; 12 const tokenId = userToken.tokenId; 13 } catch (error) { 14 console.error('Failed to create token:', error.message); 15 } ``` * Python ```python 1 try: 2 user_token = scalekit_client.tokens.create_token( 3 organization_id=organization_id, 4 user_id="usr_12345", 5 custom_claims={ 6 "team": "engineering", 7 "environment": "production", 8 }, 9 description="Deployment service token", 10 ) 11 12 opaque_token = user_token.token 13 token_id = user_token.token_id 14 except Exception as e: 15 print(f"Failed to create token: {e}") ``` * Go ```go 1 userToken, err := scalekitClient.Token().CreateToken( 2 ctx, organizationId, scalekit.CreateTokenOptions{ 3 UserId: "usr_12345", 4 CustomClaims: map[string]string{ 5 "team": "engineering", 6 "environment": "production", 7 }, 8 Description: "Deployment service token", 9 }, 10 ) 11 if err != nil { 12 log.Printf("Failed to create user token: %v", err) 13 return 14 } 15 16 opaqueToken := userToken.Token 17 tokenId := userToken.TokenId ``` * Java ```java 1 import java.util.Map; 2 import com.scalekit.grpc.scalekit.v1.tokens.CreateTokenResponse; 3 4 try { 5 Map customClaims = Map.of( 6 "team", "engineering", 7 "environment", "production" 8 ); 9 10 CreateTokenResponse userToken = scalekitClient.tokens().create( 11 organizationId, "usr_12345", customClaims, null, "Deployment service token" 12 ); 13 14 String opaqueToken = userToken.getToken(); 15 String tokenId = userToken.getTokenId(); 16 } catch (Exception e) { 17 System.err.println("Failed to create token: " + e.getMessage()); 18 } ``` The response contains three fields: | Field | Description | | ------------ | ---------------------------------------------------------------------------------------- | | `token` | The API key string. **Returned only at creation.** | | `token_id` | An identifier (format: `apit_xxxxx`) for referencing the token in management operations. | | `token_info` | Metadata including organization, user, custom claims, and timestamps. | 3. ## Validate a token [Section titled “Validate a token”](#validate-a-token) When your API server receives a request with an API key, you’ll want to verify it’s legitimate before processing the request. Pass the key to Scalekit — it validates the key server-side and returns the associated organization, user, and metadata context. * Node.js ```javascript 1 import { ScalekitValidateTokenFailureException } from '@scalekit-sdk/node'; 2 3 try { 4 const result = await scalekit.token.validateToken(opaqueToken); 5 6 const orgId = result.tokenInfo?.organizationId; 7 const userId = result.tokenInfo?.userId; 8 const claims = result.tokenInfo?.customClaims; 9 } catch (error) { 10 if (error instanceof ScalekitValidateTokenFailureException) { 11 // Token is invalid, expired, or revoked 12 console.error('Token validation failed:', error.message); 13 } 14 } ``` * Python ```python 1 from scalekit import ScalekitValidateTokenFailureException 2 3 try: 4 result = scalekit_client.tokens.validate_token(token=opaque_token) 5 6 org_id = result.token_info.organization_id 7 user_id = result.token_info.user_id 8 claims = result.token_info.custom_claims 9 except ScalekitValidateTokenFailureException: 10 # Token is invalid, expired, or revoked 11 print("Token validation failed") ``` * Go ```go 1 result, err := scalekitClient.Token().ValidateToken(ctx, opaqueToken) 2 if errors.Is(err, scalekit.ErrTokenValidationFailed) { 3 // Token is invalid, expired, or revoked 4 log.Printf("Token validation failed: %v", err) 5 return 6 } 7 8 orgId := result.TokenInfo.OrganizationId 9 userId := result.TokenInfo.GetUserId() // *string — nil for org-scoped tokens 10 claims := result.TokenInfo.CustomClaims ``` * Java ```java 1 import java.util.Map; 2 import com.scalekit.exceptions.TokenInvalidException; 3 import com.scalekit.grpc.scalekit.v1.tokens.ValidateTokenResponse; 4 5 try { 6 ValidateTokenResponse result = scalekitClient.tokens().validate(opaqueToken); 7 8 String orgId = result.getTokenInfo().getOrganizationId(); 9 String userId = result.getTokenInfo().getUserId(); 10 Map claims = result.getTokenInfo().getCustomClaimsMap(); 11 } catch (TokenInvalidException e) { 12 // Token is invalid, expired, or revoked 13 System.err.println("Token validation failed: " + e.getMessage()); 14 } ``` If the API key is invalid, expired, or has been revoked, validation fails with a specific error that you can catch and handle in your code. This makes it easy to reject unauthorized requests in your API middleware. ### Access roles and organization details [Section titled “Access roles and organization details”](#access-roles-and-organization-details) Beyond the basic organization and user information, the validation response also includes any roles assigned to the user and external identifiers you’ve configured for the organization. These are useful for making authorization decisions without additional database lookups. * Node.js ```javascript 1 try { 2 const result = await scalekit.token.validateToken(opaqueToken); 3 4 // Roles assigned to the user 5 const roles = result.tokenInfo?.roles; 6 7 // External identifiers for mapping to your system 8 const externalOrgId = result.tokenInfo?.organizationExternalId; 9 const externalUserId = result.tokenInfo?.userExternalId; 10 } catch (error) { 11 if (error instanceof ScalekitValidateTokenFailureException) { 12 console.error('Token validation failed:', error.message); 13 } 14 } ``` * Python ```python 1 try: 2 result = scalekit_client.tokens.validate_token(token=opaque_token) 3 4 # Roles assigned to the user 5 roles = result.token_info.roles 6 7 # External identifiers for mapping to your system 8 external_org_id = result.token_info.organization_external_id 9 external_user_id = result.token_info.user_external_id 10 except ScalekitValidateTokenFailureException: 11 print("Token validation failed") ``` * Go ```go 1 result, err := scalekitClient.Token().ValidateToken(ctx, opaqueToken) 2 if errors.Is(err, scalekit.ErrTokenValidationFailed) { 3 log.Printf("Token validation failed: %v", err) 4 return 5 } 6 7 // Roles assigned to the user 8 roles := result.TokenInfo.Roles 9 10 // External identifiers for mapping to your system 11 externalOrgId := result.TokenInfo.OrganizationExternalId 12 externalUserId := result.TokenInfo.GetUserExternalId() // *string — nil if no external ID ``` * Java ```java 1 import java.util.List; 2 import com.scalekit.exceptions.TokenInvalidException; 3 import com.scalekit.grpc.scalekit.v1.tokens.ValidateTokenResponse; 4 5 try { 6 ValidateTokenResponse result = scalekitClient.tokens().validate(opaqueToken); 7 8 // Roles assigned to the user 9 List roles = result.getTokenInfo().getRolesList(); 10 11 // External identifiers for mapping to your system 12 String externalOrgId = result.getTokenInfo().getOrganizationExternalId(); 13 String externalUserId = result.getTokenInfo().getUserExternalId(); 14 } catch (TokenInvalidException e) { 15 System.err.println("Token validation failed: " + e.getMessage()); 16 } ``` ### Access custom metadata [Section titled “Access custom metadata”](#access-custom-metadata) If you attached custom claims when creating the API key, they come back in every validation response. This is a convenient way to make fine-grained authorization decisions — like restricting access by team or environment — without hitting your database. * Node.js ```javascript 1 try { 2 const result = await scalekit.token.validateToken(opaqueToken); 3 4 const team = result.tokenInfo?.customClaims?.team; 5 const environment = result.tokenInfo?.customClaims?.environment; 6 7 // Use metadata for authorization 8 if (environment !== 'production') { 9 return res.status(403).json({ error: 'Production access required' }); 10 } 11 } catch (error) { 12 if (error instanceof ScalekitValidateTokenFailureException) { 13 console.error('Token validation failed:', error.message); 14 } 15 } ``` * Python ```python 1 try: 2 result = scalekit_client.tokens.validate_token(token=opaque_token) 3 4 team = result.token_info.custom_claims.get("team") 5 environment = result.token_info.custom_claims.get("environment") 6 7 # Use metadata for authorization 8 if environment != "production": 9 return jsonify({"error": "Production access required"}), 403 10 except ScalekitValidateTokenFailureException: 11 print("Token validation failed") ``` * Go ```go 1 result, err := scalekitClient.Token().ValidateToken(ctx, opaqueToken) 2 if errors.Is(err, scalekit.ErrTokenValidationFailed) { 3 log.Printf("Token validation failed: %v", err) 4 return 5 } 6 7 team := result.TokenInfo.CustomClaims["team"] 8 environment := result.TokenInfo.CustomClaims["environment"] 9 10 // Use metadata for authorization 11 if environment != "production" { 12 c.JSON(403, gin.H{"error": "Production access required"}) 13 return 14 } ``` * Java ```java 1 import java.util.Map; 2 import com.scalekit.exceptions.TokenInvalidException; 3 import com.scalekit.grpc.scalekit.v1.tokens.ValidateTokenResponse; 4 5 try { 6 ValidateTokenResponse result = scalekitClient.tokens().validate(opaqueToken); 7 8 String team = result.getTokenInfo().getCustomClaimsMap().get("team"); 9 String environment = result.getTokenInfo().getCustomClaimsMap().get("environment"); 10 11 // Use metadata for authorization 12 if (!"production".equals(environment)) { 13 return ResponseEntity.status(403).body(Map.of("error", "Production access required")); 14 } 15 } catch (TokenInvalidException e) { 16 System.err.println("Token validation failed: " + e.getMessage()); 17 } ``` 4. ## List tokens [Section titled “List tokens”](#list-tokens) You can retrieve all active API keys for an organization at any time. The response supports pagination for large result sets, and you can filter by user to find keys scoped to a specific person. * Node.js ```javascript 1 try { 2 // List tokens for an organization 3 const response = await scalekit.token.listTokens(organizationId, { 4 pageSize: 10, 5 }); 6 7 for (const token of response.tokens) { 8 console.log(token.tokenId, token.description); 9 } 10 11 // Paginate through results 12 if (response.nextPageToken) { 13 const nextPage = await scalekit.token.listTokens(organizationId, { 14 pageSize: 10, 15 pageToken: response.nextPageToken, 16 }); 17 } 18 19 // Filter tokens by user 20 const userTokens = await scalekit.token.listTokens(organizationId, { 21 userId: 'usr_12345', 22 }); 23 } catch (error) { 24 console.error('Failed to list tokens:', error.message); 25 } ``` * Python ```python 1 try: 2 # List tokens for an organization 3 response = scalekit_client.tokens.list_tokens( 4 organization_id=organization_id, 5 page_size=10, 6 ) 7 8 for token in response.tokens: 9 print(token.token_id, token.description) 10 11 # Paginate through results 12 if response.next_page_token: 13 next_page = scalekit_client.tokens.list_tokens( 14 organization_id=organization_id, 15 page_size=10, 16 page_token=response.next_page_token, 17 ) 18 19 # Filter tokens by user 20 user_tokens = scalekit_client.tokens.list_tokens( 21 organization_id=organization_id, 22 user_id="usr_12345", 23 ) 24 except Exception as e: 25 print(f"Failed to list tokens: {e}") ``` * Go ```go 1 // List tokens for an organization 2 response, err := scalekitClient.Token().ListTokens( 3 ctx, organizationId, scalekit.ListTokensOptions{ 4 PageSize: 10, 5 }, 6 ) 7 if err != nil { 8 log.Printf("Failed to list tokens: %v", err) 9 return 10 } 11 12 for _, token := range response.Tokens { 13 fmt.Println(token.TokenId, token.GetDescription()) 14 } 15 16 // Paginate through results 17 if response.NextPageToken != "" { 18 nextPage, err := scalekitClient.Token().ListTokens( 19 ctx, organizationId, scalekit.ListTokensOptions{ 20 PageSize: 10, 21 PageToken: response.NextPageToken, 22 }, 23 ) 24 if err != nil { 25 log.Printf("Failed to fetch next page: %v", err) 26 return 27 } 28 _ = nextPage // process nextPage.Tokens 29 } 30 31 // Filter tokens by user 32 userTokens, err := scalekitClient.Token().ListTokens( 33 ctx, organizationId, scalekit.ListTokensOptions{ 34 UserId: "usr_12345", 35 }, 36 ) 37 if err != nil { 38 log.Printf("Failed to list user tokens: %v", err) 39 return 40 } 41 _ = userTokens // process userTokens.Tokens ``` * Java ```java 1 import com.scalekit.grpc.scalekit.v1.tokens.ListTokensResponse; 2 import com.scalekit.grpc.scalekit.v1.tokens.Token; 3 4 try { 5 ListTokensResponse response = scalekitClient.tokens().list(organizationId, 10, null); 6 for (Token token : response.getTokensList()) { 7 System.out.println(token.getTokenId() + " " + token.getDescription()); 8 } 9 } catch (Exception e) { 10 System.err.println("Failed to list tokens: " + e.getMessage()); 11 } 12 13 try { 14 ListTokensResponse response = scalekitClient.tokens().list(organizationId, 10, null); 15 if (!response.getNextPageToken().isEmpty()) { 16 ListTokensResponse nextPage = scalekitClient.tokens().list( 17 organizationId, 10, response.getNextPageToken() 18 ); 19 } 20 } catch (Exception e) { 21 System.err.println("Failed to paginate tokens: " + e.getMessage()); 22 } 23 24 try { 25 ListTokensResponse userTokens = scalekitClient.tokens().list( 26 organizationId, "usr_12345", 10, null 27 ); 28 } catch (Exception e) { 29 System.err.println("Failed to list user tokens: " + e.getMessage()); 30 } ``` The response includes `totalCount` for the total number of matching tokens and `nextPageToken` / `prevPageToken` cursors for navigating pages. 5. ## Invalidate a token [Section titled “Invalidate a token”](#invalidate-a-token) When you need to revoke an API key — for example, when an employee leaves or you suspect credentials have been compromised — you can invalidate it through Scalekit. Revocation takes effect instantly: the very next validation request for that key will fail. This operation is **idempotent**, so calling invalidate on an already-revoked key succeeds without error. * Node.js ```javascript 1 try { 2 // Invalidate by API key string 3 await scalekit.token.invalidateToken(opaqueToken); 4 5 // Or invalidate by token_id (useful when you store tokenId for lifecycle management) 6 await scalekit.token.invalidateToken(tokenId); 7 } catch (error) { 8 console.error('Failed to invalidate token:', error.message); 9 } ``` * Python ```python 1 try: 2 # Invalidate by API key string 3 scalekit_client.tokens.invalidate_token(token=opaque_token) 4 5 # Or invalidate by token_id (useful when you store token_id for lifecycle management) 6 scalekit_client.tokens.invalidate_token(token=token_id) 7 except Exception as e: 8 print(f"Failed to invalidate token: {e}") ``` * Go ```go 1 // Invalidate by API key string 2 if err := scalekitClient.Token().InvalidateToken(ctx, opaqueToken); err != nil { 3 log.Printf("Failed to invalidate token: %v", err) 4 } 5 6 // Or invalidate by token_id (useful when you store tokenId for lifecycle management) 7 if err := scalekitClient.Token().InvalidateToken(ctx, tokenId); err != nil { 8 log.Printf("Failed to invalidate token: %v", err) 9 } ``` * Java ```java 1 try { 2 // Invalidate by API key string 3 scalekitClient.tokens().invalidate(opaqueToken); 4 5 // Or invalidate by token_id (useful when you store tokenId for lifecycle management) 6 scalekitClient.tokens().invalidate(tokenId); 7 } catch (Exception e) { 8 System.err.println("Failed to invalidate token: " + e.getMessage()); 9 } ``` 6. ## Protect your API endpoints [Section titled “Protect your API endpoints”](#protect-your-api-endpoints) Now let’s put it all together. The most common pattern is to add API key validation as middleware in your API server. Extract the Bearer token from the `Authorization` header, validate it through Scalekit, and use the returned context for authorization decisions. * Node.js Express.js ```javascript 1 import { ScalekitValidateTokenFailureException } from '@scalekit-sdk/node'; 2 3 async function authenticateToken(req, res, next) { 4 const authHeader = req.headers['authorization']; 5 const token = authHeader && authHeader.split(' ')[1]; 6 7 if (!token) { 8 // Reject requests without credentials to prevent unauthorized access 9 return res.status(401).json({ error: 'Missing authorization token' }); 10 } 11 12 try { 13 // Server-side validation — Scalekit checks token status in real time 14 const result = await scalekit.token.validateToken(token); 15 // Attach token context to the request for downstream handlers 16 req.tokenInfo = result.tokenInfo; 17 next(); 18 } catch (error) { 19 if (error instanceof ScalekitValidateTokenFailureException) { 20 // Revoked, expired, or malformed tokens are rejected immediately 21 return res.status(401).json({ error: 'Invalid or expired token' }); 22 } 23 throw error; 24 } 25 } 26 27 // Apply to protected routes 28 app.get('/api/resources', authenticateToken, (req, res) => { 29 const orgId = req.tokenInfo.organizationId; 30 // Serve resources scoped to this organization 31 }); ``` * Python Flask ```python 1 from functools import wraps 2 from flask import request, jsonify, g 3 from scalekit import ScalekitValidateTokenFailureException 4 5 def authenticate_token(f): 6 @wraps(f) 7 def decorated(*args, **kwargs): 8 auth_header = request.headers.get("Authorization", "") 9 if not auth_header.startswith("Bearer "): 10 # Reject requests without credentials to prevent unauthorized access 11 return jsonify({"error": "Missing authorization token"}), 401 12 13 token = auth_header.split(" ")[1] 14 15 try: 16 # Server-side validation — Scalekit checks token status in real time 17 result = scalekit_client.tokens.validate_token(token=token) 18 # Attach token context for downstream handlers 19 g.token_info = result.token_info 20 except ScalekitValidateTokenFailureException: 21 # Revoked, expired, or malformed tokens are rejected immediately 22 return jsonify({"error": "Invalid or expired token"}), 401 23 24 return f(*args, **kwargs) 25 return decorated 26 27 # Apply to protected routes 28 @app.route("/api/resources") 29 @authenticate_token 30 def get_resources(): 31 org_id = g.token_info.organization_id 32 # Serve resources scoped to this organization ``` * Go Gin ```go 1 func AuthenticateToken(scalekitClient scalekit.Scalekit) gin.HandlerFunc { 2 return func(c *gin.Context) { 3 authHeader := c.GetHeader("Authorization") 4 if !strings.HasPrefix(authHeader, "Bearer ") { 5 // Reject requests without credentials to prevent unauthorized access 6 c.JSON(401, gin.H{"error": "Missing authorization token"}) 7 c.Abort() 8 return 9 } 10 11 token := strings.TrimPrefix(authHeader, "Bearer ") 12 13 // Server-side validation — Scalekit checks token status in real time 14 result, err := scalekitClient.Token().ValidateToken(c.Request.Context(), token) 15 if err != nil { 16 if errors.Is(err, scalekit.ErrTokenValidationFailed) { 17 // Revoked, expired, or malformed tokens are rejected immediately 18 c.JSON(401, gin.H{"error": "Invalid or expired token"}) 19 } else { 20 // Surface transport or unexpected errors as 500 21 c.JSON(500, gin.H{"error": "Internal server error"}) 22 } 23 c.Abort() 24 return 25 } 26 27 // Attach token context for downstream handlers 28 c.Set("tokenInfo", result.TokenInfo) 29 c.Next() 30 } 31 } 32 33 // Apply to protected routes 34 r.GET("/api/resources", AuthenticateToken(scalekitClient), func(c *gin.Context) { 35 tokenInfo := c.MustGet("tokenInfo").(*scalekit.TokenInfo) 36 orgId := tokenInfo.OrganizationId 37 // Serve resources scoped to this organization 38 }) ``` * Java Spring Boot ```java 1 import com.scalekit.exceptions.TokenInvalidException; 2 import com.scalekit.grpc.scalekit.v1.tokens.Token; 3 import com.scalekit.grpc.scalekit.v1.tokens.ValidateTokenResponse; 4 5 @Component 6 public class TokenAuthFilter extends OncePerRequestFilter { 7 private final ScalekitClient scalekitClient; 8 9 public TokenAuthFilter(ScalekitClient scalekitClient) { 10 this.scalekitClient = scalekitClient; 11 } 12 13 @Override 14 protected void doFilterInternal( 15 HttpServletRequest request, 16 HttpServletResponse response, 17 FilterChain filterChain 18 ) throws ServletException, IOException { 19 String authHeader = request.getHeader("Authorization"); 20 if (authHeader == null || !authHeader.startsWith("Bearer ")) { 21 // Reject requests without credentials to prevent unauthorized access 22 response.sendError(401, "Missing authorization token"); 23 return; 24 } 25 26 String token = authHeader.substring(7); 27 28 try { 29 // Server-side validation — Scalekit checks token status in real time 30 ValidateTokenResponse result = scalekitClient.tokens().validate(token); 31 // Attach token context for downstream handlers 32 request.setAttribute("tokenInfo", result.getTokenInfo()); 33 filterChain.doFilter(request, response); 34 } catch (TokenInvalidException e) { 35 // Revoked, expired, or malformed tokens are rejected immediately 36 response.sendError(401, "Invalid or expired token"); 37 } 38 } 39 } 40 41 // Access in your controller 42 @GetMapping("/api/resources") 43 public ResponseEntity getResources(HttpServletRequest request) { 44 Token tokenInfo = (Token) request.getAttribute("tokenInfo"); 45 String orgId = tokenInfo.getOrganizationId(); 46 // Serve resources scoped to this organization 47 } ``` ### Using validation context for data filtering [Section titled “Using validation context for data filtering”](#using-validation-context-for-data-filtering) After validation succeeds, your middleware has access to the organization and (optionally) user context. Use this context to filter the data your endpoint returns — no additional database queries needed. **For organization-scoped keys**: Extract the organization ID from the validation response. Your endpoint then returns resources belonging to that organization. If a customer authenticates with an organization-scoped key, they get access to all their workspace data. **For user-scoped keys**: Extract both organization ID and user ID. Filter your query to return only resources belonging to that user within the organization. If a team member authenticates with a user-scoped key, they see only their assigned tasks, their owned projects, or their allocated resources — depending on your application logic. The validation response is your source of truth. Trust the organization and user context it provides, and use it to build your authorization queries without additional lookups. Here are a few tips to help you get the most out of API keys in production: * **Store API keys securely**: Treat API keys like passwords. Store them in encrypted secrets managers or environment variables. Never log keys, commit them to version control, or expose them in client-side code. * **Set expiry for time-limited access**: Use the `expiry` parameter for keys that should automatically become invalid after a set period. This limits the blast radius if a key is compromised. * **Use custom claims for context**: Attach metadata like `team`, `environment`, or `service` as custom claims. Your API middleware can use these claims for fine-grained authorization without additional database lookups. * **Rotate keys safely**: To rotate an API key, create a new key, update the consuming service to use the new key, verify the new key works, then invalidate the old key. This avoids downtime during rotation. You now have everything you need to issue, validate, and manage API keys in your application. --- # DOCUMENT BOUNDARY --- # Authenticate customer apps > Use Scalekit to implement OAuth for customer apps. Issue tokens and validate API requests with JWKS This guide explains how you enable API authentication for your customers’ applications using Scalekit’s OAuth 2.0 client credentials flow. When your customers build applications that need to access your API, they use client credentials registered through your Scalekit environment to obtain access tokens. Your API validates these tokens to authorize their requests using JWKS. ## How your customers’ applications authenticate with your API [Section titled “How your customers’ applications authenticate with your API”](#how-your-customers-applications-authenticate-with-your-api) Your Scalekit environment functions as an OAuth 2.0 Authorization Server. Your customers’ applications authenticate using the client credentials flow, exchanging their registered client ID and secret for access tokens that authorize API requests to your platform. ### Storing client credentials [Section titled “Storing client credentials”](#storing-client-credentials) Your customers’ applications securely store the credentials you issued to them in environment variables. This example shows how their applications would store these credentials: Environment variables in customer's application ```sh 1 YOURAPP_ENVIRONMENT_URL="" 2 YOURAPP_CLIENT_ID="" 3 YOURAPP_CLIENT_SECRET="" ``` These credentials are obtained when you register an API client for your customer (see the [quickstart guide](/authenticate/m2m/api-auth-quickstart/) for client registration). ### Obtaining access tokens [Section titled “Obtaining access tokens”](#obtaining-access-tokens) Your customers’ applications obtain access tokens from your Scalekit authorization server before making API requests. They send their credentials to your token endpoint: Token endpoint ```sh 1 https:///oauth/token ``` Here’s how your customers’ applications request access tokens: * cURL ```sh 1 curl -X POST \ 2 "https:///oauth/token" \ 3 -H "Content-Type: application/x-www-form-urlencoded" \ 4 -d "grant_type=client_credentials" \ 5 -d "client_id=" \ 6 -d "client_secret=" \ 7 -d "scope=openid profile email" ``` * Python ```python 1 import os 2 import json 3 import requests 4 5 # Customer's application configuration 6 env_url = os.environ['YOURAPP_SCALEKIT_ENVIRONMENT_URL'] 7 8 def get_m2m_access_token(): 9 """ 10 Customer's application requests an access token using client credentials. 11 This token will be used to authenticate API requests to your platform. 12 """ 13 headers = {"Content-Type": "application/x-www-form-urlencoded"} 14 params = { 15 "grant_type": "client_credentials", 16 "client_id": os.environ['YOURAPP_SCALEKIT_CLIENT_ID'], 17 "client_secret": os.environ['YOURAPP_SCALEKIT_CLIENT_SECRET'], 18 "scope": "openid profile email" 19 } 20 21 response = requests.post( 22 url=f"{env_url}/oauth/token", 23 headers=headers, 24 data=params, 25 verify=True 26 ) 27 28 access_token = response.json().get('access_token') 29 return access_token ``` Your authorization server returns a JSON response containing the access token: Token response ```json 1 { 2 "access_token": "", 3 "token_type": "Bearer", 4 "expires_in": 86399, 5 "scope": "openid" 6 } ``` | Field | Description | | -------------- | ----------------------------------------------------- | | `access_token` | Token for authenticating API requests | | `token_type` | Always “Bearer” for this flow | | `expires_in` | Token validity period in seconds (typically 24 hours) | | `scope` | Authorized scopes for this token | ### Using access tokens [Section titled “Using access tokens”](#using-access-tokens) After obtaining an access token, your customers’ applications include it in the Authorization header when making requests to your API: Customer's application making an API request ```sh 1 curl --request GET "https://" \ 2 -H "Content-Type: application/json" \ 3 -H "Authorization: Bearer " ``` ## Validating access tokens [Section titled “Validating access tokens”](#validating-access-tokens) Your API server must validate access tokens before processing requests. Scalekit uses JSON Web Tokens (JWTs) signed with RSA keys, which you validate using the JSON Web Key Set (JWKS) endpoint. ### Retrieving JWKS [Section titled “Retrieving JWKS”](#retrieving-jwks) Your application should fetch the public keys from the JWKS endpoint: JWKS endpoint ```sh 1 https:///keys ``` JWKS response ```json 1 { 2 "keys": [ 3 { 4 "use": "sig", 5 "kty": "RSA", 6 "kid": "snk_58327480989122566", 7 "alg": "RS256", 8 "n": "wUaqIj3pIE_zfGN9u4GySZs862F-0Kl-..", 9 "e": "AQAB" 10 } 11 ] 12 } ``` ### Token validation process [Section titled “Token validation process”](#token-validation-process) When your API receives a request with a JWT, follow these steps: 1. Extract the token from the Authorization header 2. Fetch the JWKS from the endpoint 3. Use the public key from JWKS to verify the token’s signature 4. Validate the token’s claims (issuer, audience, expiration) This example shows how to fetch JWKS data: Fetch JWKS with cURL ```sh 1 curl -s "https:///keys" | jq ``` * jwksClient (Node.js) Express.js ```javascript 1 const express = require('express'); 2 const jwt = require('jsonwebtoken'); 3 const jwksClient = require('jwks-rsa'); 4 const app = express(); 5 6 // Initialize JWKS client to validate tokens from customer applications 7 // This fetches public keys from your Scalekit environment 8 const client = jwksClient({ 9 jwksUri: `https:///keys` 10 }); 11 12 // Function to get signing key for token verification 13 function getKey(header, callback) { 14 client.getSigningKey(header.kid, function(err, key) { 15 if (err) return callback(err); 16 17 const signingKey = key.publicKey || key.rsaPublicKey; 18 callback(null, signingKey); 19 }); 20 } 21 22 // Middleware to validate JWT from customer's API client application 23 function validateJwt(req, res, next) { 24 // Extract token sent by customer's application 25 const authHeader = req.headers.authorization; 26 if (!authHeader || !authHeader.startsWith('Bearer ')) { 27 return res.status(401).json({ error: 'Missing authorization token' }); 28 } 29 30 const token = authHeader.split(' ')[1]; 31 32 // Verify the token signature using JWKS 33 jwt.verify(token, getKey, { 34 algorithms: ['RS256'] 35 }, (err, decoded) => { 36 if (err) { 37 return res.status(401).json({ error: 'Invalid token', details: err.message }); 38 } 39 40 // Token is valid - add decoded claims to request 41 req.user = decoded; 42 next(); 43 }); 44 } 45 46 // Apply validation middleware to your API routes 47 app.use('/api', validateJwt); 48 49 // Example protected API endpoint 50 app.get('/api/data', (req, res) => { 51 res.json({ 52 message: 'Customer application authenticated successfully', 53 userId: req.user.sub 54 }); 55 }); 56 57 app.listen(3000, () => { 58 console.log('API server running on port 3000'); 59 }); ``` * Python Flask ```python 1 from scalekit import ScalekitClient 2 import os 3 4 # Initialize Scalekit SDK to validate tokens from customer applications 5 scalekit_client = ScalekitClient( 6 env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), 7 client_id=os.getenv("SCALEKIT_CLIENT_ID"), 8 client_secret=os.getenv("SCALEKIT_CLIENT_SECRET") 9 ) 10 11 def validate_api_request(request): 12 """ 13 Validate access token from customer's API client application. 14 Your API uses this to authorize requests from customer applications. 15 """ 16 # Extract token sent by customer's application 17 auth_header = request.headers.get('Authorization') 18 if not auth_header or not auth_header.startswith('Bearer '): 19 return None, "Missing authorization token" 20 21 token = auth_header.split(' ')[1] 22 23 try: 24 # Validate token and extract claims using Scalekit SDK 25 claims = scalekit_client.validate_access_token_and_get_claims( 26 token=token 27 ) 28 29 # Token is valid - return claims for authorization logic 30 return claims, None 31 except Exception as e: 32 return None, f"Invalid token: {str(e)}" 33 34 # Example: Use in your Flask API endpoint 35 @app.route('/api/data', methods=['GET']) 36 def get_data(): 37 claims, error = validate_api_request(request) 38 39 if error: 40 return {"error": error}, 401 41 42 # Customer application is authenticated 43 return { 44 "message": "Customer application authenticated successfully", 45 "userId": claims.get("sub") 46 } ``` ### SDK support status [Section titled “SDK support status”](#sdk-support-status) All Scalekit SDKs include helpers for validating access tokens: * **Node.js**: Provides `validateAccessToken` and `validateToken` methods with `TokenValidationOptions` for validating issuer, audience, and required scopes. * **Python**: Provides `validate_access_token`, `validate_token`, and `validate_access_token_and_get_claims` methods with `TokenValidationOptions` for validating issuer, audience, and required scopes. * **Go**: Provides `ValidateAccessToken`, generic `ValidateToken[T]`, and `GetAccessTokenClaims` helpers that validate tokens using JWKS and return typed claims with errors. These methods accept `context.Context` as the first argument for cancellation and timeout. * **Java**: Provides `validateAccessToken` (boolean) and `validateAccessTokenAndGetClaims` (returns claims and throws `APIException`) for token validation in JVM applications. You can still use standard JWT libraries with the JWKS endpoint, as shown in the examples above, when you need custom validation logic or cannot use an SDK in your API service.