---
title: "Register an agent and start a claim ceremony"
method: POST
path: "/agent/auth"
tags: ["agent-auth"]
---

# Register an agent and start a claim ceremony

`POST /agent/auth`

## Request

- Base URL: `https://www.supersetapp.com`
- URL: `https://www.supersetapp.com/agent/auth`
- Auth: none required

Step 3 of the auth.md profile: an agent registers itself and gets back a claim URL for a person to open. Anonymous, service_auth, and identity_assertion registrations are supported. See https://www.supersetapp.com/auth.md.

## Request body

- object

## Response `200`

The registration, with the ceremony to relay when there is one.

- union: A registered agent. Which fields arrive depends on the type.
  - AnonymousRegistration: No person yet: a catalog assertion now, a claim to run later.
    - `registration_id` string, required
    - `registration_type` 'anonymous', required
    - `identity_assertion` string, required: Exchange it at the token endpoint for a catalog credential.
    - `assertion_expires` string, date-time, required
    - `pre_claim_scopes` string[], required
    - `claim_url` string, uri, required
    - `claim_token` string, required: Present it at `claim_url`.
    - `claim_token_expires` string, date-time, required
    - `post_claim_scopes` string[], required
  - ServiceAuthRegistration: An email was offered; the ceremony below proves the person behind it.
    - `registration_id` string, required
    - `registration_type` 'service_auth', required
    - `claim_url` string, uri, required
    - `claim_token` string, required
    - `claim_token_expires` string, date-time, required
    - `post_claim_scopes` string[], required
    - `claim` Ceremony, required: RFC 8628-shaped: the code a person types, and where.
      - `user_code` string, required: What the person types.
      - `verification_uri` string, uri, required: Where they type it.
      - `expires_in` integer, required: Seconds the code lasts.
      - `interval` integer, required: Seconds between polls.
  - LinkedRegistration: The provider subject was already linked, so the assertion is issued now.
    - `registration_id` string, required
    - `registration_type` 'identity_assertion', required
    - `identity_assertion` string, required
    - `assertion_expires` string, date-time, required
    - `scopes` string[], required: What this assertion reaches.
    - `claim_token` string: Only on the registration that mints one.

## Other responses

- `400`: The registration was malformed.
- `401`: `interaction_required` carries a ceremony to relay to the person; `login_required` carries `max_age` and none.
- `429`: Too many registrations. Back off and retry.

---

[API](https://skmtc.dev/supersetapp/apis/superset-api.md) - [All operations](https://skmtc.dev/supersetapp/apis/superset-api/llms.txt) - [OpenAPI document](https://skmtc.dev/supersetapp/apis/superset-api/revisions/80be14a3d402?raw)