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/v9" | |
| ) | |
| 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", | |
| "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" | |
| } |
Feature flagged
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/v9" | |
| ) | |
| 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" | |
| } |
Feature flagged
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/v9" | |
| ) | |
| 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" | |
| } | |
| ] | |
| } |
Feature flagged
PATCH/agents
Returns
Audit Logs Continue to the next section
Up next