Agent authorization ~ SHIP

Let an agent register itself, get a person to claim it, and trade its assertion for access tokens. Also list and revoke the agents that you authorized.

Authorization server metadata (RFC 8414)

Response Body

`application/json`

curl -X GET "https://example.com/oauth/authorization-server"

{  "issuer": "string",  "token_endpoint": "string",  "revocation_endpoint": "string",  "jwks_uri": "string",  "grant_types_supported": [    "string"  ],  "scopes_supported": [    "string"  ],  "token_endpoint_auth_methods_supported": [    "string"  ],  "agent_auth": {    "property1": null,    "property2": null  }}

Protected resource metadata (RFC 9728)

Query Parameters

resource*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/oauth/protected-resource?resource=string"

{  "resource": "string",  "resource_name": "string",  "authorization_servers": [    "string"  ],  "scopes_supported": [    "string"  ],  "bearer_methods_supported": [    "string"  ],  "resource_documentation": "string"}

Signing keys (JWKS)

Response Body

`application/json`

curl -X GET "https://example.com/oauth2/jwks"

{  "keys": [    {      "property1": null,      "property2": null    }  ]}

Register an agent (Auth.md)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

type*"anonymous"

Value in

"anonymous"

agent_name?string

What the agent calls itself. Shown on the claim page as the agent's own words; the person names the delegation.

Lengthlength <= 200

Response Body

`application/json`

curl -X POST "https://example.com/agent/identity" \  -H "Content-Type: application/json" \  -d '{    "type": "anonymous"  }'

{  "registration_id": "string",  "registration_type": "anonymous",  "identity_assertion": "string",  "assertion_expires": "string",  "pre_claim_scopes": [    "string"  ],  "scopes": [    "string"  ],  "claim_url": "string",  "claim_token": "string",  "claim_token_expires": "string",  "post_claim_scopes": [    "string"  ],  "claim": {    "user_code": "string",    "verification_uri": "string",    "expires_in": 0,    "interval": 0  }}

Start or renew a claim

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

claim_token*string

Length1 <= length <= 200

email*string

Length1 <= length <= 320

Response Body

`application/json`

curl -X POST "https://example.com/agent/identity/claim" \  -H "Content-Type: application/json" \  -d '{    "claim_token": "string",    "email": "string"  }'

{  "registration_id": "string",  "claim_attempt_id": "string",  "status": "initiated",  "expires_at": "string",  "claim_attempt": {    "user_code": "string",    "verification_uri": "string",    "expires_in": 0,    "interval": 0  }}

Token endpoint

Request Body

application/x-www-form-urlencoded

TypeScript Definitions

Use the request body type in TypeScript.

grant_type*string

assertion?string

claim_token?string

resource?string

RFC 8707 resource: the API (default) or the MCP server.

code?string

redirect_uri?string

client_id?string

code_verifier?string

refresh_token?string

Response Body

`application/json`

curl -X POST "https://example.com/oauth2/token" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'grant_type=string'

{  "access_token": "string",  "token_type": "Bearer",  "expires_in": 0,  "scope": "string",  "refresh_token": "string",  "identity_assertion": "string",  "assertion_expires": "string"}

Revoke an access token (RFC 7009)

Request Body

application/x-www-form-urlencoded

TypeScript Definitions

Use the request body type in TypeScript.

token*string

token_type_hint?string

Response Body

`application/json`

curl -X POST "https://example.com/oauth2/revoke" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'token=string'

Empty

Receive a Security Event Token (RFC 8935)

Request Body

application/secevent+jwt

TypeScript Definitions

Use the request body type in TypeScript.

body*string

Response Body

`application/json`

curl -X POST "https://example.com/agent/event/notify" \  -H "Content-Type: application/secevent+jwt" \  -d 'string'

Empty

Read a claim link

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

claimAttemptToken*string

Length1 <= length <= 200

Response Body

`application/json`

curl -X POST "https://example.com/agent/claims/resolve" \  -H "Content-Type: application/json" \  -d '{    "claimAttemptToken": "string"  }'

{  "state": "ready",  "signedInEmail": "string",  "boundEmail": "string",  "registration": {    "id": "string",    "kind": "anonymous",    "agentName": "string",    "providerName": "string"  },  "advisories": [    {      "kind": "first_time_account",      "providerName": "string"    }  ],  "grantOptions": {    "orgs": [      {        "id": "string",        "name": "string",        "role": "string",        "grantableScopes": [          "string"        ],        "projects": [          {            "id": "string",            "name": "string"          }        ]      }    ],    "defaultOrgId": "string",    "defaultExpiresInDays": 0,    "maxExpiresInDays": 0  },  "codeExpiresAt": 0,  "attemptsLeft": 0}

Claim an agent

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

orgId*string

Length1 <= length

scopes?array<string>

Itemsitems <= 25

Default[]

projectId?string

Length1 <= length

expiresInDays?integer

Range1 <= value <= 365

name*string

Length1 <= length <= 100

claimAttemptToken*string

Length1 <= length <= 200

userCode*string

Match^\d{6}$

Response Body

`application/json`

curl -X POST "https://example.com/agent/claims/complete" \  -H "Content-Type: application/json" \  -d '{    "orgId": "string",    "name": "string",    "claimAttemptToken": "string",    "userCode": "string"  }'

{  "status": "claimed",  "delegation": {    "id": "string",    "name": "string",    "source": "string",    "orgId": "string",    "projectId": "string",    "scopes": [      "string"    ],    "providerName": "string",    "createdAt": 0,    "expiresAt": 0,    "revokedAt": 0,    "lastUsedAt": 0  }}

List the agents you authorized

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/agent-delegations"

{  "data": [    {      "id": "string",      "name": "string",      "source": "string",      "orgId": "string",      "projectId": "string",      "scopes": [        "string"      ],      "providerName": "string",      "createdAt": 0,      "expiresAt": 0,      "revokedAt": 0,      "lastUsedAt": 0    }  ]}

Revoke an agent

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

delegationId*string

Length1 <= length

Response Body

`application/json`

curl -X DELETE "https://example.com/agent-delegations/string"

{  "kind": "revoked",  "delegationId": "string",  "revokedAt": 0,  "revokedTokens": 0}

Register an OAuth client (RFC 7591)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

redirect_uris*array<string>

client_name?string

Lengthlength <= 200

client_uri?string

logo_uri?string

grant_types?array<string>

response_types?array<string>

token_endpoint_auth_method?string

application_type?string

Response Body

`application/json`

curl -X POST "https://example.com/oauth2/register" \  -H "Content-Type: application/json" \  -d '{    "redirect_uris": [      "string"    ]  }'

{  "client_id": "string",  "client_id_issued_at": 0,  "client_name": "string",  "redirect_uris": [    "string"  ],  "grant_types": [    "string"  ],  "response_types": [    "string"  ],  "token_endpoint_auth_method": "none"}

Open an authorization request

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

response_type?string

client_id?string

redirect_uri?string

code_challenge?string

code_challenge_method?string

state?string

Lengthlength <= 2000

scope?string

Lengthlength <= 2000

resource?string

Response Body

`application/json`

curl -X POST "https://example.com/oauth/authorizations" \  -H "Content-Type: application/json" \  -d '{}'

{  "kind": "consent",  "requestId": "string",  "client": {    "clientId": "string",    "name": "string",    "clientUri": "string",    "registration": "dcr"  },  "redirectHost": "string",  "redirectIsLoopback": true,  "resource": "api",  "requestedScopes": [    "string"  ],  "offlineAccess": true,  "signedInEmail": "string",  "grantOptions": {    "orgs": [      {        "id": "string",        "name": "string",        "role": "string",        "grantableScopes": [          "string"        ],        "projects": [          {            "id": "string",            "name": "string"          }        ]      }    ],    "defaultOrgId": "string",    "defaultExpiresInDays": 0,    "maxExpiresInDays": 0  }}

Approve an authorization request

Path Parameters

requestId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

orgId*string

Length1 <= length

scopes?array<string>

Itemsitems <= 25

Default[]

projectId?string

Length1 <= length

expiresInDays?integer

Range1 <= value <= 365

name?string

Length1 <= length <= 100

Response Body

`application/json`

curl -X POST "https://example.com/oauth/authorizations/string/approve" \  -H "Content-Type: application/json" \  -d '{    "orgId": "string"  }'

{  "redirectTo": "string"}

Deny an authorization request

Path Parameters

requestId*string

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/oauth/authorizations/string/deny"

{  "redirectTo": "string"}

Agent authorization

200application/json

500application/json

200application/json

404application/json

200application/json

500application/json

200application/json

400application/json

401application/json

429application/json

503application/json

200application/json

400application/json

401application/json

409application/json

410application/json

200application/json

400application/json

500application/json

200

400application/json

202

400application/json

200application/json

401application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

410application/json

429application/json

500application/json

200application/json

404application/json

200application/json

404application/json

201application/json

400application/json

429application/json

200application/json

401application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

410application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

410application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`