---
title: "Register an agent as an OAuth client"
method: POST
path: "/oauth/agent/register"
tags: ["Agents"]
---

# Register an agent as an OAuth client

`POST /oauth/agent/register`

## Request

- Base URL: `https://api.customdomain.ai`
- URL: `https://api.customdomain.ai/oauth/agent/register`
- Auth: none required

Dynamic Client Registration (RFC 7591). An AI assistant registers itself as a public client (PKCE, no secret) and can do nothing until a person approves a grant for it in the console. Registration is open on purpose, so it is bounded: a per-IP hourly budget on top of the global limit, and a client that nobody ever approves into a workspace is deleted after a while. Other client metadata (`client_uri`, `logo_uri`, `scope`, `contacts`, ...) is accepted and ignored. A `client_name` that claims a well known brand (Claude, ChatGPT, ...) is refused unless every redirect host belongs to that brand or is a loopback address. Errors use the RFC 7591 envelope.

## Request body

- AgentClientRegistration: RFC 7591 client metadata. Anything else a client sends (`client_uri`, `logo_uri`, `scope`, `contacts` and so on) is accepted and ignored.
  - `client_name` string, required: Shown to the person who approves the agent. At most 100 characters, with no control or invisible characters and no Latin letters mixed with look-alike letters from another alphabet. A name that claims a well known brand is refused unless every redirect host belongs to that brand or is a loopback address.
  - `redirect_uris` string[], required: Where the authorization code may be sent. `https`, or `http` on a loopback host (`localhost`, `127.0.0.1`, `::1`) for a program on the person's own computer. No fragment and no user information. A redirect URI is matched exactly later, except for the port of a loopback one.
  - `grant_types` string[]: Optional. When sent it must include `authorization_code`; other values are ignored. The client is registered for `authorization_code` and `refresh_token`.
  - `response_types` string[]: Optional. When sent it must include `code`.
  - `token_endpoint_auth_method` string: Ignored. Every agent client is a public client (`none`) and PKCE protects its code.

## Response `201`

The registered client

- AgentClient
  - `client_id` string, required: Starts with `agc_`.
  - `client_id_issued_at` integer, required: Unix time of the registration.
  - `client_name` string, required
  - `redirect_uris` string[], required: The registered URIs, normalized.
  - `token_endpoint_auth_method` 'none', required
  - `grant_types` string[], required
  - `response_types` string[], required

## Other responses

- `400`: `invalid_client_metadata` (a bad or impersonating name, grant or response types without the authorization code grant) or `invalid_redirect_uri` (none, more than 10, a fragment, user information, or http on a host that is not loopback).
- `429`: Error envelope: {code, title, details}.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)