ApiKey
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- Types:
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:
user.createApiKey()user.listApiKeys()user.useApiKeys()(React hook)team.createApiKey()team.listApiKeys()team.useApiKeys()(React hook)
Table of Contents
The unique identifier for this API key.
declare const id: string;A human-readable description of the API key's purpose.
declare const description: string;The date and time when this API key will expire. If not set, the key does not expire.
declare const expiresAt?: Date;The date and time when this API key was manually revoked. If null, the key has not been revoked.
declare const manuallyRevokedAt: Date | null;The date and time when this API key was created.
declare const createdAt: Date;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.
// On first creation
declare const value: string;
// On subsequent retrievals
declare const value: { lastFour: string };For user API keys, the ID of the user that owns this API key.
declare const userId: string;For team API keys, the ID of the team that owns this API key.
declare const teamId: string;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.
declare function isValid(): boolean;if (apiKey.isValid()) {
console.log("API key is still valid");
} else {
console.log("API key is invalid");
}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.
declare function whyInvalid(): "manually-revoked" | "expired" | null;const reason = apiKey.whyInvalid();
if (reason) {
console.log(`API key is invalid because it was ${reason}`);
} else {
console.log("API key is valid");
}Revokes the API key, preventing it from being used for authentication.
Parameters
None.
Returns
Promise<void>
declare function revoke(): Promise<void>;await apiKey.revoke();
console.log("API key has been revoked");Updates the API key properties.
Parameters
optionsobjectrequiredAn object containing properties for updating.
Show Properties
descriptionstringA new description for the API key.
expiresAtDate | nullA new expiration date, or null to remove the expiration.
revokedbooleanSet to true to revoke the API key.
Returns
Promise<void>
declare function update(options: {
description?: string;
expiresAt?: Date | null;
revoked?: boolean;
}): Promise<void>;await apiKey.update({
description: "Updated description",
expiresAt: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000), // 60 days
});Types
A type alias for an API key owned by a user.
type UserApiKey = ApiKey<"user", false>;A type alias for a newly created user API key, which includes the full key value instead of just the last four characters.
type UserApiKeyFirstView = ApiKey<"user", true>;A type alias for an API key owned by a team.
type TeamApiKey = ApiKey<"team", false>;A type alias for a newly created team API key, which includes the full key value instead of just the last four characters.
type TeamApiKeyFirstView = ApiKey<"team", true>;Creation Options
When creating an API key using user.createApiKey() or team.createApiKey(), you need to provide an options object.
The options object for creating an API key.
Properties
descriptionstringrequiredA human-readable description of the API key's purpose.
expiresAtDate | nullrequiredThe date when the API key will expire. Use null for keys that don't expire.
isPublicbooleanWhether 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.
type ApiKeyCreationOptions = {
description: string;
expiresAt: Date | null;
isPublic?: boolean;
};// Get the current user
const user = await stackApp.getUser();
// Create a secret API key (default)
const secretKey = await user.createApiKey({
description: "Backend integration",
expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000), // 90 days
isPublic: false,
});
// Create a public API key
const publicKey = await user.createApiKey({
description: "Client-side access",
expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
isPublic: true,
});