# Create account

Provisions the verified identity's account. Idempotent: calling it again for an already-provisioned identity returns the same account unchanged. It is the only call an unprovisioned identity may make; every other endpoint requires this to have run first.

`POST /v1/users`

## Authentication

Both headers are required.

- Header: `X-Api-Key: YOUR_API_KEY`
- Header: `Authorization: Bearer YOUR_USER_TOKEN`

## Request body



```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    }
  }
}
```


## Request example

Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it.

```sh
curl --request POST 'https://api.example.test/v1/users' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

## Responses

### 200

The provisioned account.



```json
{
  "description": "The provisioned account.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      }
    }
  }
}
```


### 400

The request could not be read as this operation expects.

- `invalid_input` — the body or query failed validation; `issues` names each field



```json
{
  "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 401

A credential is missing, invalid or expired.

- `partner_key_required` — no `X-Api-Key` header was sent
- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked
- `credential_expired` — the user token has expired; obtain a fresh one



```json
{
  "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 403

The credentials are valid but may not do this.

- `account_disabled` — an operator disabled the account
- `origin_rejected` — a browser `Origin` other than the configured web origin



```json
{
  "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 413

The body exceeds the size this deployment accepts.



```json
{
  "description": "The body exceeds the size this deployment accepts.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 429

A limiter refused the request; honour `Retry-After`.

- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`



```json
{
  "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 500

A fault on our side; quote `requestId` when reporting it.

- `internal` — a fault on our side; quote `requestId` when reporting it



```json
{
  "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


### 503

The replica is draining or a dependency did not answer; `retryable` says whether to try again.

- `internal` — a fault on our side; quote `requestId` when reporting it



```json
{
  "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```


## Complete OpenAPI definition

The exact operation and all referenced components, including recursive schemas.



```json
{
  "operation": {
    "operationId": "users.ensure",
    "summary": "Create account",
    "tags": [
      "users"
    ],
    "description": "Provisions the verified identity's account. Idempotent: calling it again for an already-provisioned identity returns the same account unchanged. It is the only call an unprovisioned identity may make; every other endpoint requires this to have run first.",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        }
      }
    },
    "security": [
      {
        "apiKey": [],
        "userToken": []
      }
    ],
    "responses": {
      "200": {
        "description": "The provisioned account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/User"
            }
          }
        }
      },
      "400": {
        "$ref": "#/components/responses/InvalidInputForRegistration"
      },
      "401": {
        "$ref": "#/components/responses/Unauthorized"
      },
      "403": {
        "$ref": "#/components/responses/ForbiddenForRegistration"
      },
      "413": {
        "$ref": "#/components/responses/PayloadTooLarge"
      },
      "429": {
        "$ref": "#/components/responses/TooManyRequests"
      },
      "500": {
        "$ref": "#/components/responses/Internal"
      },
      "503": {
        "$ref": "#/components/responses/Unavailable"
      }
    },
    "parameters": []
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512,
            "description": "The verified identity's subject, from the login provider."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
            "description": "When the credential expires; the caller must re-authenticate after this."
          },
          "userId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The user's account id."
          }
        },
        "required": [
          "subject",
          "expiresAt",
          "userId"
        ],
        "description": "The verified caller: their account id, verified subject and when the credential expires."
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "The kind of problem as a URN, `urn:fin:error:<kind>`; stable, compare against it"
          },
          "title": {
            "type": "string",
            "description": "The kind's human title, for logs; never parse it"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "The HTTP status, repeated in the body"
          },
          "reason": {
            "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (409) — the user's spend headroom is gone, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (409) — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` (409) — the execution engine could not take the work\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the `revision` sent is stale; reload the automation\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_completed` (409) — the automation has finished for good and cannot fire again\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (409) — the run profile names a tool this deployment does not have\n- `deployment_paused` (409) — an operator paused a deployment control; nothing was admitted or fired\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `account_not_provisioned` (412) — the identity is verified but has no account yet; call `users.ensure` first\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `engine_unavailable` (503) — the execution engine did not answer\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the operator credential lacks the scope this call needs\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `stream_capacity` (429) — no stream socket is free on this replica or for this user; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted",
            "type": "string",
            "enum": [
              "run_active",
              "budget_exhausted",
              "approval_not_pending",
              "execution_capacity",
              "execution_unavailable",
              "stop_pending",
              "automation_changed",
              "automation_held",
              "automation_invalid",
              "automation_completed",
              "automation_limit",
              "profile_unknown_tool",
              "deployment_paused",
              "run_not_active",
              "withdrawal_changed",
              "credential_expired",
              "account_disabled",
              "account_not_provisioned",
              "provider_unavailable",
              "engine_unavailable",
              "invalid_input",
              "internal",
              "partner_key_required",
              "partner_key_invalid",
              "subject_mismatch",
              "origin_rejected",
              "permission_required",
              "rate_limited",
              "stream_capacity",
              "invalid_cursor"
            ]
          },
          "requestId": {
            "type": "string",
            "description": "The id Fin used for this request; quote it when reporting a problem"
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether repeating the same request later can succeed without changing it"
          },
          "detail": {
            "description": "Only on `invalid_input`: which part of the request failed validation",
            "type": "string"
          },
          "issues": {
            "description": "Only on `invalid_input`: one entry per failing field",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string",
                  "description": "The JSON pointer of the failing field; empty for the root object"
                },
                "message": {
                  "type": "string",
                  "description": "Why the field failed"
                }
              },
              "required": [
                "path",
                "message"
              ]
            }
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "requestId",
          "retryable"
        ],
        "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack."
      }
    },
    "responses": {
      "InvalidInputForRegistration": {
        "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "ForbiddenForRegistration": {
        "description": "The credentials are valid but may not do this.\n\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The body exceeds the size this deployment accepts.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Internal": {
        "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unavailable": {
        "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "userToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}
```