API Keys

API keys provide a secure way for your application’s users to authenticate with your API. IT contacts create API keys through the API Keys Widget, and your application can validate these keys to authenticate API requests.

Read more about API keys in AuthKit.

The owner.type field distinguishes organization-owned keys from user-owned keys. Organization-owned keys include an organization ID in owner.id. User-owned keys include the user ID in owner.id and the organization the key can access in owner.organization_id.

The full API key value is returned only when a key is created. Later list, validate, and object responses include obfuscated_value, but not value.

Get a list of all API keys for an organization.

curl "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/api_keys" \
  --header "Authorization: Bearer sk_example_123456789"

Creates a new API key for the specified organization. The response includes the full API key value, which is only returned once at creation time. Make sure to store this value securely as it cannot be retrieved again.

You can optionally specify permissions to control what actions the API key can perform. If no permissions are provided, the key will have no specific permissions assigned.

curl --request POST \
  --url "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/api_keys" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Production API Key",
        "permissions": [
            "posts:read",
            "posts:write"
        ]
    }
BODY

Permanently deletes an API key. This action cannot be undone. Once deleted, any requests using this API key will fail authentication.

curl --request DELETE \
  --url "https://api.workos.com/api_keys/api_key_01EHZNVPK3SFK441A1RGBFSHRT" \
  --header "Authorization: Bearer sk_example_123456789"

Validates an API key and returns its associated metadata if the key is valid. Your application’s API uses this endpoint to authenticate incoming requests that include an API key.

The endpoint returns the complete API key object when validation succeeds, allowing you to access the key’s permissions and owner information for authorization purposes. If the key is invalid, the endpoint returns null for the api_key field.

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

const workos = new WorkOS('sk_example_123456789');

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