Create API Key

Generate a new API key for programmatic access to DialNexa. The secret is returned only once at creation.

POST /api-keys

Create an API key

cURL

curl --request POST \
  --url https://api.dialnexa.com/v1/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Production Server",
  "expire_now": false
}
'

201

{
  "id": "YOUR_API_KEY",
  "name": "Production Server",
  "secret": "YOUR_API_KEY",
  "created_at": "2024-03-01T10:00:00.000Z"
}

Generates a new API key. The secret value is returned only once: in the response of this call. DialNexa does not store the secret in a recoverable form, so if you lose it you must revoke the key with Revoke API Key and create a new one. Keys are scoped to the workspace they are created in and inherit the permissions of the caller that created them.

When to use this

• First-time setup: issue the initial key for a new environment.
• New consumer service: issue a dedicated key for each upstream service so you can revoke them independently if needed.
• Planned rotation: issue the next key as the first step in the Key rotation playbook.
• Environment separation: keep production, staging, and development keys distinct so a leak in one environment does not compromise the others.

Best practices

• One key per environment. Create separate keys for development, staging, and production so revocation never takes down more than one environment at a time.
• One key per consumer service. If multiple services share a key, a leak forces you to rotate every consumer at once. Per-service keys narrow the blast radius.
• Never commit keys to source control. Use environment variables or a secrets manager. Keys accidentally pushed to a public repository should be revoked immediately, even if you delete the commit.
• Rotate periodically. Issue a new key, deploy it everywhere it is needed, verify traffic on the new key through List API Keys’ last_used_at field, then revoke the old one.

Authentication

Use the returned secret as a Bearer token in the Authorization header on every API request:

curl https://api.dialnexa.com/v1/agents2 \
  -H "Authorization: Bearer YOUR_API_KEY"

Body parameters

Field	Description
name	Display name for the new key, for example Production Server or Acme CRM Integration.

Errors

• 400 Bad Request is returned when the name field is missing or empty.
• 403 Forbidden is returned when the caller does not have permission to create API keys.

Request

curl -X POST "https://api.dialnexa.com/v1/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Server"}'

Response

{
  "id": "key_abc123",
  "name": "Production Server",
  "secret": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2024-05-01T10:00:00Z"
}

The secret field appears only in this response. Store it in your secrets manager before continuing.

Related endpoints

• List API Keys: review every key on the workspace.
• Rename API Key: change a key’s display name.
• Revoke API Key: permanently retire a key.
• Key rotation: recommended sequence for rotating keys without downtime.
• Authentication: how keys are sent and verified.

Authorizations

Authorization · string · header · required

Pass your API key as a Bearer token in the Authorization header.

Body

application/json

name · string · required

A descriptive label for this key.

Example:

"Production Server"

expire_now · boolean

If true, the key is created already expired. Useful for testing revocation flows.

Example:

false

Response

201 - application/json

API key created. The secret field is only returned in this response.

id · string

Example:

"YOUR_API_KEY"

name · string

Example:

"Production Server"

secret · string

The API key secret. Shown only once - store it securely immediately.

Example:

"YOUR_API_KEY"

created_at · string<date-time>

Example:

"2024-03-01T10:00:00.000Z"