Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/workos/workos-node/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The API Keys API allows you to programmatically manage and validate API keys used by your organization. This is useful for building internal tools, implementing security workflows, or managing API key lifecycles.

​
Methods

​
validateApiKey

Validates an API key and retrieves its details.
​
payload
ValidateApiKeyOptions
required
Validation options
​
ValidateApiKeyResponse
object
Validation response

​
Example - Valid Key

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const result = await workos.apiKeys.validateApiKey({
  value: 'sk_live_1234567890abcdef',
});

if (result.apiKey) {
  console.log('Valid API key:', result.apiKey.name);
  console.log('Permissions:', result.apiKey.permissions);
  console.log('Last used:', result.apiKey.lastUsedAt);
} else {
  console.log('Invalid API key');
}

​
Response - Valid Key

{
  "apiKey": {
    "id": "api_key_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1",
    "object": "api_key",
    "owner": {
      "type": "organization",
      "id": "org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1"
    },
    "name": "Production API Key",
    "obfuscatedValue": "sk_live_****cdef",
    "lastUsedAt": "2024-03-01T15:30:00Z",
    "permissions": [
      "user_management:read",
      "organizations:write"
    ],
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-03-01T15:30:00Z"
  }
}

​
Response - Invalid Key

{
  "apiKey": null
}

​
deleteApiKey

Deletes an API key by its ID.
​
id
string
required
The unique identifier of the API key to delete
​
void
void
Returns nothing on successful deletion

​
Example

await workos.apiKeys.deleteApiKey('api_key_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1');

console.log('API key deleted successfully');
Deleting an API key immediately revokes access. Any applications or services using this key will no longer be able to authenticate.

​
Use Cases

Key Validation

Verify API keys before processing requests in your application

Key Rotation

Implement automated key rotation workflows for enhanced security

Audit Trail

Track API key usage and last access times for compliance

Access Control

Validate permissions before allowing access to sensitive operations

​
Security Best Practices

Never commit API keys to version control. Use environment variables or secret management services like AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault.
Implement a key rotation schedule (e.g., every 90 days) to minimize the impact of potential key compromise.
Create API keys with only the permissions necessary for their intended use case.
Track lastUsedAt timestamps to identify unused or suspicious API key activity.
Immediately delete API keys that may have been exposed or compromised.

​
Example - Key Rotation Workflow

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

async function rotateApiKey(oldKeyValue: string) {
  // Step 1: Validate the old key
  const validation = await workos.apiKeys.validateApiKey({
    value: oldKeyValue,
  });
  
  if (!validation.apiKey) {
    throw new Error('Invalid API key');
  }
  
  // Step 2: Create new key (via WorkOS Dashboard or API)
  // Note: Key creation typically happens through the WorkOS Dashboard
  console.log('Create a new API key in the WorkOS Dashboard');
  
  // Step 3: Update your application to use the new key
  console.log('Update environment variables with new key');
  
  // Step 4: Delete the old key
  await workos.apiKeys.deleteApiKey(validation.apiKey.id);
  
  console.log('Old API key deleted successfully');
}

// Usage
rotateApiKey('sk_live_old_key_value');

Authentication

Learn about WorkOS authentication concepts

Client Initialization

Initialize the WorkOS client with API keys

Organizations

Manage organization-scoped API keys

Audit Logs

Track API key usage in audit logs

Build docs developers (and LLMs) love

Get started for freeTalk to us