Ctrlk
Sign up for FreeKnowledge Base
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agentic client registration API

Register, list, and update the MCP clients that authenticate to a server behind the P0 AI Gateway.

Register the MCP clients that authenticate to a server behind the P0 AI Gateway, list the clients you have already registered, and update a client's display name or status. A client is the identity your agent presents to the gateway.

Use these endpoints to script client registration, to audit the clients already registered, and to rename or disable a client after registration. For the end-to-end walkthrough that includes the console path and a Python client example, see Connect an MCP client.

The Agentic Gateway integration is available as an opt-in capability. Contact P0 to enable it for your organization.

Authentication

Pass a bearer token on every call. {orgId} is your P0 tenant slug, the same value that appears in console URLs at p0.app/o/{orgId}/....

The endpoints authenticate differently:

  • POST /clients (register) requires a user token: a bearer token from a session signed in as a P0 user, because P0 derives the client owner from the caller's identity. P0 rejects an API key with 400. Register through the console, or get a user token from the P0 CLI.

  • GET /clients (list) accepts a user token or an API key.

  • PATCH /clients/{clientId} (update) accepts a user token or an API key, because an API key always acts as owner.

# List clients with an API key.
curl -H "Authorization: Bearer $P0_API_TOKEN" \
  https://api.p0.app/o/$P0_TENANT/agentic/clients

Registering a client requires the agentic.client.create permission, held by the viewer, manager, and owner roles. Viewer is the base role, so any user in your sign-in domain can register. Listing requires agentic.client.read, held by the iamViewer, iamOwner, manager, and owner roles, so a user who can register cannot necessarily list. Updating requires agentic.client.update, held by the manager and owner roles.

Client types

The type field selects which kind of client you register:

  • client_credential_post: a confidential client that authenticates with a client secret P0 issues. This is the user-delegated path used by Connect an MCP client. The secret is returned only once, in the registration response.

  • jwt_bearer: a federated agent identity that authenticates with a token from an installed identity provider. P0 does not issue a secret. Register these only when dynamic registration is disabled for the provider. See Register an agent identity.

A confidential client's secret is shown once, in the registration response. Store it securely before discarding the response. If you lose it, register a new client.

Update a client

PATCH /clients/{clientId} changes a client's display name or status. This works for both confidential and federated clients. Send at least one of the two fields below and nothing else; an empty request returns 400, and so does an unrecognized field. The response is the updated client, with secrets removed.

  • displayName: a human-friendly name for the client, no longer than 100 characters. P0 trims leading and trailing whitespace, but measures the limit against the name as sent, before trimming. Send null to clear the saved name. A blank or whitespace-only name returns 400, and so does one over the limit.

  • status: active or disabled. Set it to disabled to stop the client from authenticating and refreshing, or back to active to restore it.

URL-encode {clientId}, because federated identity IDs contain slashes. If no client matches, P0 returns 404.

API reference

agentic-client-registration-api.yaml
13KB
Open

Register an MCP client

post

Registers a client that an agent presents to the gateway. Requires the agentic.client.create permission. For a confidential client, the response contains a secret that is returned only once. Select the variant with the type field.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
or
Responses
200

The registered client. Confidential clients include the one-time secret.

application/json
clientone ofOptional
or
post/clients
POST /o/demo-org/agentic/clients HTTP/1.1
Host: api.p0.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "type": "client_credential_post",
  "platform": "claude-code",
  "redirectUri": "text",
  "hostname": "text",
  "version": "text"
}
{
  "client": {
    "id": "text",
    "type": "client_credential_post",
    "displayName": "text",
    "createdAt": 1,
    "createdBy": {
      "user": "text",
      "ip": "text",
      "gateway": "text"
    },
    "platform": "claude-code",
    "redirectUri": "text",
    "hostname": "text",
    "version": "text",
    "status": "active",
    "secret": "text"
  }
}

List registered MCP clients

get

Returns every registered client, ordered newest first. Requires the agentic.client.read permission. Secrets are never returned.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Responses
200

The registered clients.

application/json
get/clients
GET /o/demo-org/agentic/clients HTTP/1.1
Host: api.p0.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "clients": [
    {
      "id": "text",
      "type": "client_credential_post",
      "displayName": "text",
      "createdAt": 1,
      "createdBy": {
        "user": "text",
        "ip": "text",
        "gateway": "text"
      },
      "platform": "claude-code",
      "redirectUri": "text",
      "hostname": "text",
      "version": "text",
      "status": "active"
    }
  ]
}

Update an MCP client

patch

Updates a registered client's display name or status. Requires the agentic.client.update permission. Include at least one field; an empty request is rejected. Returns the updated client. Secrets are never returned.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
clientIdstringRequired

The client ID. URL-encode it, because federated identity IDs contain slashes.

Body

Update a registered client's display name or status. Include at least one field; an empty object is rejected. These are the only fields accepted; any other field is rejected.

displayNamestring · min: 1 · max: 100 · nullableOptional

A human-friendly client name, no longer than 100 characters. P0 trims leading and trailing whitespace, but measures the limit against the value as sent, before trimming. Send null to clear the saved value. A blank or whitespace-only value is rejected.

Pattern: \S
statusstring · enumOptional

Whether the client may authenticate and refresh. Set to disabled to stop the client from authenticating.

Possible values:
Responses
200

The updated client.

application/json
clientone ofRequired
or
patch/clients/{clientId}
PATCH /o/demo-org/agentic/clients/{clientId} HTTP/1.1
Host: api.p0.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "displayName": "text",
  "status": "active"
}
{
  "client": {
    "id": "text",
    "type": "client_credential_post",
    "displayName": "text",
    "createdAt": 1,
    "createdBy": {
      "user": "text",
      "ip": "text",
      "gateway": "text"
    },
    "platform": "claude-code",
    "redirectUri": "text",
    "hostname": "text",
    "version": "text",
    "status": "active"
  }
}

Related

  • Connect an MCP client: the full walkthrough, including the console path and a Python client example.

  • Identity provider: register federated agent identities.

  • JWT-SVID: connect an unattended workload instead of a user-delegated client.

PreviousConnect an MCP client
NextJWT-SVID

Last updated