Skip to main content
cURL

Get your Exa API key

Create a key in the dashboard. New accounts start with free credits.
The Team Management API is enabled per team. It authenticates with a service account API key, which is created from the Service keys tab on the API keys page once the feature is enabled for your team. Contact support@exa.ai to request access.

Overview

Rotating replaces a key’s secret in place. The key keeps its publicId, name, rate limit, budget, and usage history, so only the secret stored in your vault changes.

Rotating on a schedule

  1. Call this endpoint with the key’s publicId and a gracePeriodSeconds long enough to roll out the new secret, for example 86400 for one day.
  2. Store apiKey.secret from the response in your secrets manager and deploy it.
  3. The old secret stops working at previousSecretExpiresAt. To cut it off sooner, call Revoke previous API key secret.
Address the key by its publicId. It never changes, while an old secret stops identifying the key once its grace period ends.

Rotating again during a grace period

A key has at most one previous secret. While the secret replaced by the last rotation is still in its grace period, a new rotation returns 409 with code set to previous_secret_active and changes nothing, so a job that fires twice cannot revoke a secret you are still deploying. Wait until previousSecretExpiresAt, revoke the previous secret first, or send "force": true to rotate anyway.

Recovering a lost response

If the rotation succeeded but your job did not receive the response, read the current secret back from the id field of Get API key using the key’s publicId.

Authorizations

x-api-key
string
header
required

Service API key for team authentication

Path Parameters

id
string
required

The key's publicId. The key's current secret, or a previous secret still in its grace period, is also accepted for backward compatibility.

Body

application/json
gracePeriodSeconds
integer
required

How long the old secret keeps working, in seconds (at most 90 days). 0 revokes it immediately.

Required range: 0 <= x <= 7776000
Example:

86400

force
boolean
default:false

Rotate even if the secret replaced by an earlier rotation is still in its grace period. That secret stops working immediately.

Response

API key rotated successfully

apiKey
object