ApiKey

This is a reference for the ApiKey type in the Next.js SDK.

Represents an API key for a user or project in Neon Auth.

On this page:

• ApiKey
• Types:
  • UserApiKey
  • TeamApiKey

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)

Type Definition

type ApiKey<Type extends "user" | "team" = "user" | "team", IsFirstView extends boolean = false> = {
  id: string;
  description: string;
  expiresAt?: Date;
  manuallyRevokedAt: Date | null;
  createdAt: Date;
  value: IsFirstView extends true ? string : { lastFour: string };

  // User or Team properties based on Type
  ...(Type extends "user" ? {
    type: "user";
    userId: string;
  } : {
    type: "team";
    teamId: string;
  })

  // Methods
  isValid(): boolean;
  whyInvalid(): "manually-revoked" | "expired" | null;
  revoke(): Promise<void>;
  update(options): Promise<void>;
};

apiKey.id

The unique identifier for this API key.

declare const id: string;

apiKey.description

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

declare const description: string;

apiKey.expiresAt

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

declare const expiresAt?: Date;

apiKey.manuallyRevokedAt

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

declare const manuallyRevokedAt: Date | null;

apiKey.createdAt

The date and time when this API key was created.

declare 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.

// On first creation
declare const value: string;

// On subsequent retrievals
declare const value: { lastFour: string };

apiKey.userId

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

declare const userId: string;

apiKey.teamId

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

declare const teamId: string;

apiKey.isValid()

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

declare function isValid(): boolean;

apiKey.whyInvalid()

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

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

apiKey.revoke()

Revokes the API key.

declare function revoke(): Promise<void>;

apiKey.update(options)

Updates the API key.

Parameters

• options: An object containing properties for updating.
  • description: The new description of the API key.
  • expiresAt: The new expiration date of the API key.

Returns

Promise<void>

declare function update(options: { description?: string; expiresAt?: Date }): Promise<void>;