Types

API Key

slug: sdk/types/api-key

ApiKey represents an authentication token that allows programmatic access to your application’s backend. API keys can be associated with individual users or teams.

On this page:

ApiKey

API keys provide a way for users to authenticate with your backend services without using their primary credentials. They can be created for individual users or for teams, allowing programmatic access to your application.

API keys can be obtained through:

Table of Contents

1type ApiKey<Type extends "user" | "team" = "user" | "team", IsFirstView extends boolean = false> = {
2  id: string;  //$stack-link-to:#apikeyid
3  description: string;  //$stack-link-to:#apikeydescription
4  expiresAt?: Date;  //$stack-link-to:#apikeyexpiresat
5  manuallyRevokedAt: Date | null;  //$stack-link-to:#apikeymanuallyrevokedat
6  createdAt: Date;  //$stack-link-to:#apikeycreatedat
7  value: IsFirstView extends true ? string : { lastFour: string };  //$stack-link-to:#apikeyvalue
8  
9  // User or Team properties based on Type
10  ...(Type extends "user" ? {
11    type: "user";
12    userId: string;  //$stack-link-to:#apikeyuserid
13  } : {
14    type: "team";
15    teamId: string;  //$stack-link-to:#apikeyteamid
16  })
17  
18  // Methods
19  isValid(): boolean;  //$stack-link-to:#apikeyisvalid
20  whyInvalid(): "manually-revoked" | "expired" | null;  //$stack-link-to:#apikeywhyinvalid
21  revoke(): Promise<void>;  //$stack-link-to:#apikeyrevoke
22  update(options): Promise<void>;  //$stack-link-to:#apikeyupdateoptions
23};

apiKey.id

The unique identifier for this API key.

Type Definition

1declare const id: string;

apiKey.description

A human-readable description of the API key’s purpose.

Type Definition

1declare const description: string;

apiKey.expiresAt

The date and time when this API key will expire. If not set, the key does not expire.

Type Definition

1declare const expiresAt?: Date;

apiKey.manuallyRevokedAt

The date and time when this API key was manually revoked. If null, the key has not been revoked.

Type Definition

1declare const manuallyRevokedAt: Date | null;

apiKey.createdAt

The date and time when this API key was created.

Type Definition

1declare const createdAt: Date;

apiKey.value

The value of the API key. When the key is first created, this is the full API key string. After that, only the last four characters are available for security reasons.

Type Definition

1// On first creation
2declare const value: string;
3
4// On subsequent retrievals
5declare const value: { lastFour: string };

apiKey.userId

For user API keys, the ID of the user that owns this API key.

Type Definition

1declare const userId: string;

apiKey.teamId

For team API keys, the ID of the team that owns this API key.

Type Definition

1declare const teamId: string;

apiKey.isValid()

Checks if the API key is still valid (not expired and not revoked).

Parameters

None.

Returns

boolean: True if the key is valid, false otherwise.

Signature

1declare function isValid(): boolean;

Examples

1if (apiKey.isValid()) {
2  console.log("API key is still valid");
3} else {
4  console.log("API key is invalid");
5}

apiKey.whyInvalid()

Returns the reason why the API key is invalid, or null if it is valid.

Parameters

None.

Returns

"manually-revoked" | "expired" | null: The reason the key is invalid, or null if it’s valid.

Signature

1declare function whyInvalid(): "manually-revoked" | "expired" | null;

Examples

1const reason = apiKey.whyInvalid();
2if (reason) {
3  console.log(`API key is invalid because it was ${reason}`);
4} else {
5  console.log("API key is valid");
6}

apiKey.revoke()

Revokes the API key, preventing it from being used for authentication.

Parameters

None.

Returns

Promise<void>

Signature

1declare function revoke(): Promise<void>;

Examples

1await apiKey.revoke();
2console.log("API key has been revoked");

apiKey.update(options)

Updates the API key properties.

Parameters

options
objectRequired

An object containing properties for updating.

description
string

A new description for the API key.

expiresAt
Date | null

A new expiration date, or null to remove the expiration.

revoked
boolean

Set to true to revoke the API key.

Returns

Promise<void>

Signature

1declare function update(options: {
2  description?: string;
3  expiresAt?: Date | null;
4  revoked?: boolean;
5}): Promise<void>;

Examples

1await apiKey.update({
2  description: "Updated description",
3  expiresAt: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000), // 60 days
4});

Types

UserApiKey

A type alias for an API key owned by a user:

1type UserApiKey = ApiKey<"user", false>;

UserApiKeyFirstView

A type alias for a newly created user API key, which includes the full key value:

1type UserApiKeyFirstView = ApiKey<"user", true>;

TeamApiKey

A type alias for an API key owned by a team:

1type TeamApiKey = ApiKey<"team", false>;

TeamApiKeyFirstView

A type alias for a newly created team API key, which includes the full key value:

1type TeamApiKeyFirstView = ApiKey<"team", true>;

Creation options

When creating an API key using user.createApiKey() or team.createApiKey(), you need to provide an options object with the following properties:

1type ApiKeyCreationOptions = {
2  description: string;
3  expiresAt: Date | null;
4  isPublic?: boolean;
5};

Properties

description
stringRequired

A human-readable description of the API key’s purpose.

expiresAt
Date | nullRequired

The date when the API key will expire. Use null for keys that don’t expire.

isPublic
boolean

Whether the API key is public. Defaults to false.

  • Secret API Keys (default) are monitored by Stack Auth’s secret scanner, which can revoke them if detected in public code repositories.
  • Public API Keys are designed for client-side code where exposure is not a concern.

Examples

1// Get the current user
2const user = await stackApp.getUser();
3
4// Create a secret API key (default)
5const secretKey = await user.createApiKey({
6  description: "Backend integration",
7  expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000), // 90 days
8  isPublic: false,
9});
10
11// Create a public API key
12const publicKey = await user.createApiKey({
13  description: "Client-side access",
14  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
15  isPublic: true,
16});