# Create scoped API key

`POST /api/keys`

Browser session only, signed-in account. name is 1–80 trimmed characters. scopes is a nonempty unique array of available scope identifiers. token is returned once. Store securely.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Audience: session.

## Request body

Required.

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": [
    "name",
    "scopes"
  ]
}
```

Example:

```json
{
  "name": "Order intake integration",
  "scopes": [
    "messages:read",
    "deliveries:read",
    "deliveries:replay"
  ]
}
```

## Responses

### 201

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "key": {
      "$ref": "#/components/schemas/Key"
    },
    "token": {
      "type": "string"
    }
  },
  "required": [
    "key",
    "token"
  ]
}
```

### 400

Invalid name or scope selection.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 503



## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/Key

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "hint": {
      "type": "string"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "lastUsedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "revokedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "scopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "name",
    "hint",
    "createdAt",
    "lastUsedAt",
    "revokedAt",
    "scopes"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```
