# Redeem an approval phrase

POST /v1/claims

Source: https://cherami.to/docs/api/access/redeem-claim



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`POST /v1/claims`

No API key needed.

Send the six-word phrase your human gave you. `credential` in the response is your API key, returned only in this response: send it as `Authorization: Bearer` on every other request.

A phrase works once. If you lose the credential or the response, ask your human for a new approval ([recovery](https://cherami.to/docs/guides/recovery)).

The key can use every inbox and all mail on the account. It creates no inbox: [list inboxes](https://cherami.to/docs/api/inboxes/list-inboxes) and use one that fits, or [create one](https://cherami.to/docs/api/inboxes/create-inbox).

### Optional signup questions [#optional-signup-questions]

When you can answer from what you already know, add `discovery_source` (how you or your human found Cherami) and `intended_use` (what the account's inboxes are for), each a few words of plain text. Omit a question rather than guess or ask your human. Answers never cause a refusal and are used only to learn how people find and use Cherami. [Privacy](https://cherami.to/privacy)

## Request body [#request-body]

JSON object, at most 4 KiB in total.

### Schema: ClaimInput [#schema-claiminput]

| Field              | Required | Type           | Meaning and constraints                                                                                     |
| ------------------ | -------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `phrase`           | Yes      | string         | The six-word phrase from your human; case and spacing don't matter.                                         |
| `discovery_source` | No       | any JSON value | Optional: how you or your human found Cherami, in a few words of plain text, at most 500 UTF-16 code units. |
| `intended_use`     | No       | any JSON value | Optional: what the account's inboxes are for, in a few words of plain text, at most 500 UTF-16 code units.  |

Unknown fields are rejected.

## curl example [#curl-example]

Save the payload as `request.json`, with the phrase your human gave you.

```json
{
  "phrase": "THE SIX WORDS FROM YOUR HUMAN"
}
```

```sh
curl --silent --show-error --include --request POST \
  "https://cherami.to/v1/claims" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json
```

## Responses [#responses]

### HTTP 201 [#http-201]

Created.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[ClaimResult](#schema-claimresult)

### HTTP 400 [#http-400]

`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.

`invalid_request`: The signup or redemption body has an unsupported field. Signup takes an empty object; redemption takes `phrase` and, optionally, `discovery_source` and `intended_use`.

`invalid_claim`: The phrase is invalid, expired or already used. Ask the human for a new one: they choose Get the message under Connect an agent at [https://cherami.to/account](https://cherami.to/account).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 403 [#http-403]

`origin_not_allowed`: Signup and redemption refuse requests carrying another site's `Origin` header. Call them from the agent's runtime, not from a web page.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 413 [#http-413]

`body_too_large`: Reduce the JSON request to the operation's body limit.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 415 [#http-415]

`unsupported_media_type`: Send `Content-Type: application/json`.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 429 [#http-429]

`rate_limited`: Too many signup or redemption requests from this network. Wait for `Retry-After`, then try again.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Retry-After`: Seconds to wait before retrying. For sending allowance it matches sufficient\_capacity\_at.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: ClaimResult [#schema-claimresult]

| Field        | Required | Type       | Meaning and constraints                       |
| ------------ | -------- | ---------- | --------------------------------------------- |
| `account_id` | Yes      | string     | Cherami resource ID.                          |
| `credential` | Yes      | string     | Your API key, returned only in this response. |
| `token_type` | Yes      | `"Bearer"` |                                               |
| `message`    | Yes      | string     |                                               |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                               |
| --------- | -------- | ------ | --------------------------------------------------------------------- |
| `code`    | Yes      | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

[Errors, limits and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)
