Agent Registration

Agent Registration enables AI agents and programmatic clients to obtain identity credentials from an AuthKit-powered service. The registration flow issues a signed identity assertion that can be exchanged at the token endpoint for an access token or API key.

{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "type": "anonymous",
  "identity": {
    "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudF9yZWdfMDFKOVEyWjNYNFk1VzZWN1U4VDlTMFIxUSIsImlzcyI6Imh0dHBzOi8vYXV0aGtpdC5leGFtcGxlLmNvbSIsImV4cCI6MTcxNjIzOTAyMn0.signature",
    "expires_at": "2025-01-15T12:00:00Z"
  },
  "claim": {
    "token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
    "expires_at": "2025-01-15T13:00:00Z",
    "url": "https://authkit_domain/claim"
  },
  "scopes": {
    "pre_claim": ["read:public"],
    "post_claim": ["read:public", "write:data"]
  }
}

• anonymous – No user identity. Receives limited scopes immediately and can optionally bind to a user via the claim ceremony.
• service_auth – Requires the user’s email. A claim ceremony is mandatory before trusted scopes are granted.
• refresh – Rotates an expiring identity assertion using a refresh token from a previous registration.

Read more about Agent Registration here.

Registers an agent identity using one of the supported identity types. The request body is a discriminated union – the type field determines which additional fields are required.

curl --request POST \
  --url "https://authkit_domain/agent/identity" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "type": "service_auth",
        "login_hint": "user@example.com"
    }
BODY

{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "type": "service_auth",
  "scopes": {
    "post_claim": ["read:public", "write:data"]
  },
  "claim": {
    "token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
    "expires_at": "2025-01-15T12:30:00Z",
    "url": "https://authkit_domain/claim",
    "attempt": {
      "verification_uri": "https://authkit_domain/claim?token=att_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
      "expires_at": "2025-01-15T12:30:00Z"
    }
  }
}

• anonymous – No additional fields required. Returns an identity assertion immediately along with a claim token for an optional claim ceremony.
• service_auth – Requires login_hint. Returns a claim token for a mandatory claim ceremony. The identity assertion is delivered after claim completion.
• refresh – Requires refresh_token. Returns a fresh identity assertion with a rotated refresh token.

• invalid_request – The request body is malformed or missing required fields for the specified type.
• invalid_login_hint – The login_hint email is invalid or not recognized.
• invalid_refresh_token – The refresh token is expired, revoked, or invalid.

Starts a claim ceremony by minting a claim attempt. The response includes a verification_uri that the agent presents to the user. The user signs in at that URL, and the claim page reveals a user_code for them to relay back to the agent.

curl --request POST \
  --url "https://authkit_domain/agent/identity/claim" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "type": "service_auth",
        "claim_token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
        "login_hint": "user@example.com"
    }
BODY

{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "type": "service_auth",
  "attempt": {
    "verification_uri": "https://authkit_domain/claim?token=att_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
    "expires_at": "2025-01-15T12:30:00Z"
  }
}

• invalid_claim_token – The claim token is expired, revoked, or invalid. Restart registration.
• invalid_login_hint – The email address is invalid or does not match the registration.

Retrieves claim details for the authenticated claim page. This endpoint requires a valid user access token in the Authorization: Bearer header and reveals the user_code that the user reads back to the agent.

The token parameter is the attempt token embedded in the verification_uri from the claim attempt response.

curl --request POST \
  --url "https://authkit_domain/agent/identity/claim/view" \
  --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "token": "att_01J9Q2Z3X4Y5W6V7U8T9S0R1Q"
    }
BODY

{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "status": "pending_confirmation",
  "user_code": "BCDF-GHJK"
}

• invalid_token – The attempt token is expired or invalid.
• unauthorized – The request is not authenticated with a valid user access token.
• email_mismatch – The signed-in user’s email does not match the registration’s login hint.

Completes the claim ceremony by submitting the user_code that the user read from the claim page. The agent provides the claim_token from its original registration response alongside the code relayed by the user.

On success, the verified identity is delivered exactly once in the response – the agent must persist it immediately.

curl --request POST \
  --url "https://authkit_domain/agent/identity/claim/complete" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "claim_token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
        "user_code": "BCDF-GHJK"
    }
BODY

{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "status": "claimed",
  "identity": {
    "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudF9yZWdfMDFKOVEyWjNYNFk1VzZWN1U4VDlTMFIxUSIsImlzcyI6Imh0dHBzOi8vYXV0aGtpdC5leGFtcGxlLmNvbSIsImV4cCI6MTcxNjIzOTAyMn0.signature",
    "expires_at": "2025-01-15T12:00:00Z",
    "refresh_token": {
      "value": "rt_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
      "expires_at": "2025-02-15T12:00:00Z"
    }
  }
}

• invalid_user_code – The user code is incorrect. Ask the user to re-read the code.
• user_code_expired – The user code has expired. Start a new claim attempt.
• claim_not_confirmed – The user has not yet signed in and viewed the code. Wait and retry.
• claim_expired – The claim has expired. Restart registration.
• claim_revoked – The claim was revoked. Restart registration.
• already_claimed – The registration has already been claimed. Restart registration.