Create API Key

POST /api/v1/keys

Generates a new API key. The full key value is returned only once in this response — store it immediately. Authenticate with a JWT.

Request body

Field	Type	Required	Description
`name`	string	Yes	Human-readable label for the key
`scopes`	string[]	No	Permission scopes (e.g. `["send"]`)

Response

Returns 200 OK:

Field	Type	Description
`key`	string	Full API key — shown only once
`api_key.id`	string	Unique key ID
`api_key.name`	string	Key label
`api_key.key_prefix`	string	First few characters of the key
`api_key.scopes`	string[]	Permission scopes
`api_key.created_at`	string	ISO 8601 timestamp
`api_key.revoked_at`	string \| null	Set when the key is revoked
`warning`	string	Reminder to store the key securely

{
  "key": "sk_live_abc123xyz...",
  "api_key": {
    "id": "key_01hx...",
    "name": "Production",
    "key_prefix": "sk_live_abc",
    "scopes": ["send"],
    "created_at": "2024-01-15T10:00:00Z",
    "revoked_at": null
  },
  "warning": "Store this key securely. It will not be shown again."
}

Code examples

curl https://api.smail.dev/api/v1/keys \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "scopes": ["send"]}'

const result = await smail.keys.create({
  name: "Production",
  scopes: ["send"],
});
// Store result.key immediately!
console.log("API key:", result.key);

result, err := client.Keys.Create(ctx, smail.CreateAPIKeyRequest{
    Name:   "Production",
    Scopes: []string{"send"},
})
// Store result.Key immediately!
fmt.Println("API key:", result.Key)

Error responses

Status	Error	Description
`401`	`unauthorized`	Missing or invalid JWT

Create API Key

Request body

Response

Code examples

Error responses

On this page