Skip to main content

Integrate Agent Delegated Access with Your APIs

Agent Delegated Access lets an AI agent authenticate with its own JumpCloud-managed identity while acting on behalf of a user or another supported subject. JumpCloud issues a signed JSON Web Token (JWT) that identifies:

  • The user or agent represented by the token
  • The agent performing the action
  • The JumpCloud organization that issued the token
  • The API or resource for which the token was issued
  • Optional group memberships

Use this guide to learn how developers can request these tokens, validate them in customer-controlled APIs, and use their claims when making authorization decisions.

Prerequisites:

  • An agent registered in JumpCloud
  • OAuth client credentials for that agent
  • A customer-controlled API that accepts JumpCloud-issued JWTs
  • The API’s resource identifier configured as an allowed audience for the agent
  • For user delegation, a JumpCloud OIDC application trusted by the agent

See Get Started: Agents for information about registering an agent and generating its client credentials.

See Get Started: Agent Delegated Access for information about enabling delegation, selecting a trusted OIDC application, and configuring allowed audiences.

How Agent Delegated Access Works​

Agent Delegated Access token flow

The customer application first obtains a user identity token through JumpCloud OIDC. The agent then authenticates with its own client credentials and exchanges that identity token for a delegated access token.

The agent presents the delegated token directly to the customer API. API traffic does not need to pass through the JumpCloud AI Gateway.

JumpCloud Authorization Server​

PurposeURL
Issuerhttps://ai.jumpcloud.com
Well-known endpointhttps://ai.jumpcloud.com/.well-known/oauth-authorization-server
Token endpointhttps://ai.jumpcloud.com/oauth/token
JSON Web Key Sethttps://ai.jumpcloud.com/.well-known/jwks.json

Request an Agent Token​

Use the OAuth 2.0 Client Credentials grant when an agent is acting as itself.

The request must include:

  • The agent’s client ID and client secret
  • The agentid scope
  • The groups scope if group claims are required
  • A resource value identifying the receiving API

The resource value must exactly match one of the agent’s configured allowed audiences.

cURL Example​

curl --request POST \
--url https://ai.jumpcloud.com/oauth/token \
--user "${AGENT_CLIENT_ID}:${AGENT_CLIENT_SECRET}" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=agentid groups" \
--data-urlencode "resource=https://api.example.com"

Successful Response​

{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "agentid groups"
}

A decoded agent token resembles:

{
"iss": "https://ai.jumpcloud.com",
"aud": "https://api.example.com",
"iat": 1793901600,
"exp": 1793905200,
"jti": "4ef95853-a3e7-4d97-997a-a43f56da4c39",
"sub": "6a4d71ded87c10908ae1d9c4",
"sub_type": "agent",
"jc_org": "6a3c69386158af9ca024a23a",
"scope": "agentid groups",
"groups": [
"6b82fe1c34d6920012345678"
]
}

Request a Delegated Token​

Use OAuth 2.0 Token Exchange, defined by RFC 8693, when the agent is acting on behalf of a user or another supported subject.

The agent authenticates with its own client credentials and sends the subject’s token in the request.

cURL Example: Agent Acting for a User​

curl --request POST \
--url https://ai.jumpcloud.com/oauth/token \
--user "${AGENT_CLIENT_ID}:${AGENT_CLIENT_SECRET}" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "scope=agentid groups" \
--data-urlencode "resource=https://api.example.com" \
--data-urlencode "subject_token=${USER_ID_TOKEN}" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:id_token"

Successful Response​

{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
"issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "agentid groups"
}

A decoded delegated token resembles:

{
"iss": "https://ai.jumpcloud.com",
"aud": "https://api.example.com",
"iat": 1793901600,
"exp": 1793905200,
"jti": "c3f1aa2b-38b5-45ee-962c-d8a4660e791f",
"sub": "6a4d71ded87c10908ae1d9c4",
"sub_type": "user",
"jc_org": "6a3c69386158af9ca024a23a",
"scope": "agentid groups",
"groups": [
"Managers",
"Employees"
],
"act": {
"sub": "6aa2ee464a82929d09ddac80",
"sub_type": "agent",
"groups": [
"6b82fe1c34d6920012345678"
]
}
}

Understand the Token Claims​

ClaimDescription
issThe JumpCloud authorization server that issued the token.
audThe API or resource for which the token was issued.
iatThe time at which the token was issued.
expThe time after which the token must be rejected.
jtiA unique identifier for the token.
subThe identity represented by the token.
sub_typeIdentifies the subject as user or agent.
jc_orgThe JumpCloud organization associated with the token.
scopeThe scopes granted to the token.
groupsOptional group memberships for the subject.
actThe agent acting on behalf of the subject.
act.subThe acting agent’s JumpCloud identifier.
act.sub_typeThe acting identity type. For this flow, it is agent.
act.groupsOptional group memberships for the acting agent.

Interpret sub together with sub_type. A user’s sub value depends on the Subject Claim configured on the trusted OIDC application. It might be a JumpCloud user ID, email address, username, or another configured attribute.

Do not assume that sub values are globally unique across subject types or trusted applications.

Group Claims​

The groups scope requests group information:

  • groups contains the subject’s groups.
  • act.groups contains the acting agent’s groups.

Was this information helpful?