Retrieve the details of an agent registration by ID. The registration is scoped to the environment of the API key used to authenticate the request.
cURL
| curl "https://api.workos.com/agents/registrations/agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.get_registration(id: "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.get_registration(id_="agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().GetRegistration(context.Background(), "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->agents()->getRegistration(id: "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.agents.getRegistration("agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.GetRegistrationAsync("agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .get_registration("agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "agent_identity": { | |
| "id": "agent_identity_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "userland_user_id": "user_01E4ZCR3C56J083X43JQXF3JK5", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| }, | |
| "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "status": "verified", | |
| "revoked_at": null, | |
| "kind": "service_auth", | |
| "claim": { | |
| "id": "agent_reg_claim_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "claim_completion": { | |
| "id": "agent_reg_claim_attempt_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z", | |
| "expires_at": "2026-01-15T12:00:00.000Z", | |
| "claimed_at": "2026-01-15T12:00:00.000Z" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z", | |
| "expires_at": "2026-01-15T12:00:00.000Z" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
GET/agents
Parameters
Returns
Validate an agent credential – an API key or access token – against the environment of the API key used to authenticate the request. This is a read-only check: it never consumes or mutates the credential.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/agents/credentials/validate" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "type": "api_key", | |
| "credential": "sk_agent_example_1234567890" | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.create_validate( | |
| type: "api_key", | |
| credential: "sk_agent_example_1234567890" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.create_validate(type="api_key", credential="sk_agent_example_1234567890") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().CreateValidate(context.Background(), &workos.AgentsCreateValidateParams{ | |
| Type: "api_key", | |
| Credential: "sk_agent_example_1234567890", | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->agents() | |
| ->createValidate( | |
| type: "api_key", | |
| credential: "sk_agent_example_1234567890", | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.agents.AgentsApi.CreateValidateOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreateValidateOptions options = CreateValidateOptions.builder() | |
| .type("api_key") | |
| .credential("sk_agent_example_1234567890") | |
| .build(); | |
| workos.agents.createValidate(options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.CreateValidateAsync(new AgentsCreateValidateOptions { | |
| Type = "api_key", | |
| Credential = "sk_agent_example_1234567890", | |
| }); |
| use workos::Client; | |
| use workos::agents::CreateValidateParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .create_validate( | |
| CreateValidateParams { | |
| type_: "api_key".into(), | |
| credential: "sk_agent_example_1234567890".into(), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "valid": true, | |
| "registration_id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "expires_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST/agents
Common
When
type is access_tokenReturns
Link an external user to a claim attempt and retrieve the code needed for the agent to complete the claim. The user is looked up by external ID; if no user exists, one is created. When the user belongs to multiple organizations, an explicit organization must be provided.
cURL
| curl --request PATCH \ | |
| --url "https://api.workos.com/agents/claims/attempts" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "type": "link_external_user", | |
| "claim_attempt_token": "cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "user": { | |
| "email": "alice@example.com", | |
| "external_id": "user_abc123" | |
| } | |
| } | |
| BODY |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const claimAttempt = await workos.agents.linkClaimAttemptToExternalUser({ | |
| claimAttemptToken: 'cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY', | |
| user: { | |
| email: 'alice@example.com', | |
| externalId: 'user_abc123', | |
| }, | |
| }); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.update_attempts( | |
| type: "link_external_user", | |
| claim_attempt_token: "cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| user: { email: "alice@example.com", external_id: "user_abc123" } | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.update_attempts( | |
| type="link_external_user", | |
| claim_attempt_token="cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| user={"email": "alice@example.com", "external_id": "user_abc123"}, | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().UpdateAttempts(context.Background(), &workos.AgentsUpdateAttemptsParams{ | |
| Type: "link_external_user", | |
| ClaimAttemptToken: "cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| User: map[string]any{"email": "alice@example.com", "external_id": "user_abc123"}, | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->agents() | |
| ->updateAttempts( | |
| type: "link_external_user", | |
| claimAttemptToken: "cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| user: ["email" => "alice@example.com", "external_id" => "user_abc123"], | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.agents.AgentsApi.UpdateAttemptsOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| UpdateAttemptsOptions options = | |
| UpdateAttemptsOptions.builder() | |
| .type("link_external_user") | |
| .claimAttemptToken("cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| .user(Map.of("email", "alice@example.com", "external_id", "user_abc123")) | |
| .build(); | |
| workos.agents.updateAttempts(options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.UpdateAttemptsAsync(new AgentsUpdateAttemptsOptions { | |
| Type = "link_external_user", | |
| ClaimAttemptToken = "cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| User = | |
| new Dictionary<string, object> { | |
| { "email", "alice@example.com" }, | |
| { "external_id", "user_abc123" }, | |
| }, | |
| }); |
| use workos::Client; | |
| use workos::agents::UpdateAttemptsParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .update_attempts( | |
| UpdateAttemptsParams { | |
| type_: "link_external_user".into(), | |
| claim_attempt_token: "cla_tkn_01EHWNCE74X7JSDV0X3SZ3KJNY".into(), | |
| user: serde_json::json!({ | |
| "email": "alice@example.com", | |
| "external_id": "user_abc123", | |
| }), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "status": "unverified", | |
| "user_code": "BCDF-GHJK", | |
| "organizations": [ | |
| { | |
| "id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "name": "Acme Corp" | |
| } | |
| ] | |
| } |
PATCH/agents
Returns
Revoke an agent registration by ID. Revocation is permanent: the registration, its identity assertions, and every access token or API key issued from it stop working, and the agent must register again. Revoking an already revoked registration succeeds and returns the original revoked_at. The registration is scoped to the environment of the API key used to authenticate the request.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/agents/registrations/agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY/revoke" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.revoke_registration(id: "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.revoke_registration(id_="agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().RevokeRegistration(context.Background(), "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->agents() | |
| ->revokeRegistration(id: "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.agents.revokeRegistration("agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.RevokeRegistrationAsync("agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .revoke_registration("agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "id": "agent_reg_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "agent_identity": { | |
| "id": "agent_identity_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "userland_user_id": "user_01E4ZCR3C56J083X43JQXF3JK5", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| }, | |
| "organization_id": "org_01EHQMYV6MBK39QC5PZXHY59C3", | |
| "status": "revoked", | |
| "revoked_at": "2026-01-15T12:00:00.000Z", | |
| "kind": "service_auth", | |
| "claim": { | |
| "id": "agent_reg_claim_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "claim_completion": { | |
| "id": "agent_reg_claim_attempt_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z", | |
| "expires_at": "2026-01-15T12:00:00.000Z", | |
| "claimed_at": "2026-01-15T12:00:00.000Z" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z", | |
| "expires_at": "2026-01-15T12:00:00.000Z" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
POST