Test Cloud - External client — Federated credentials

test-cloud

latest

false

Test Cloud API guide

External client — Federated credentials

Federated credentials for OAuth external applications in Test Cloud, enabling JWT-based authentication without requiring a client secret.

Federated credentials let an OAuth external application authenticate to UiPath using a JSON Web Token (JWT) issued by an external identity provider, without requiring a client secret. Each application supports a maximum of 20 federated credentials.

Note:

Federated credentials for external applications is an API-only feature. There is no user interface for managing federated credentials.

Use the endpoints on this page to list, create, retrieve, update, and delete federated credentials for a registered OAuth external application. To manage external applications themselves, see Managing external OAuth applications.

Replace {accessURL} in all endpoint paths with the base URL for your cloud platform:

Cloud platform	Access URL
Test Cloud	`https://cloud.uipath.com/`
Test Cloud Public Sector	`https://govcloud.uipath.us/`
Test Cloud Dedicated	`https://{customURL}.dedicated.uipath.com/`

List federated credentials

Retrieve all federated credentials registered for a specific OAuth external application.

API endpoint

GET {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials

Path parameters

Parameter	Description
`partitionGlobalId`	The organization global ID.
`clientId`	The ID of the OAuth external application.

Scopes

Requires either one of the following scopes:

PM.OAuthApp
PM.OAuthApp.Read

Request headers

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

Note:

To obtain the {access_token}, use an organization administrator token or authenticate through one of the methods described in Authentication methods.

Responses

200 OK

Returns an array of FederatedCredentialDto objects. Returns an empty array if no credentials are registered.

Example request

curl --request GET \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials' \
  --header 'Authorization: Bearer {access_token}'
curl --request GET \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials' \
  --header 'Authorization: Bearer {access_token}'

Example response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
    "name": "GitHub Actions",
    "description": "Used for GitHub Actions CI/CD pipeline",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main",
    "createdAt": "2026-03-01T10:00:00Z",
    "updatedAt": "2026-03-01T10:00:00Z"
  }
]
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
    "name": "GitHub Actions",
    "description": "Used for GitHub Actions CI/CD pipeline",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main",
    "createdAt": "2026-03-01T10:00:00Z",
    "updatedAt": "2026-03-01T10:00:00Z"
  }
]

Create a federated credential

Create a federated identity credential for a specific OAuth external application.

Note:

Each application supports a maximum of 20 federated credentials.

API endpoint

POST {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials

Path parameters

Parameter	Description
`partitionGlobalId`	The organization global ID.
`clientId`	The ID of the OAuth external application.

Scopes

Requires either one of the following scopes:

PM.OAuthApp
PM.OAuthApp.Write

Request headers

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

Request body

{
  "name": "azure-production-workload",
  "description": "Federated credential for production Azure workload",
  "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "audience": "api://uipath-production",
  "subject": "00000000-0000-0000-0000-000000000000"
}
{
  "name": "azure-production-workload",
  "description": "Federated credential for production Azure workload",
  "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "audience": "api://uipath-production",
  "subject": "00000000-0000-0000-0000-000000000000"
}

Field	Required	Description
`name`	Yes	A descriptive name for the credential. Must be unique within the application. Maximum 128 characters.
`description`	No	Optional context for the credential. Maximum 512 characters.
`issuer`	Yes	The HTTPS URI of the external identity provider. Must be reachable at create time.
`audience`	Yes	A single string that must appear in the JWT `aud` claim.
`subject`	Yes	A value that must exactly match the JWT `sub` claim.

Responses

201 Created

Returns the created FederatedCredentialDto object.

400 Bad Request

The request is invalid. Possible causes: name is not unique within the client, issuer is not a valid HTTPS URI, the issuer's JWKS endpoint is unreachable, or the maximum of 20 credentials per application has been reached.

404 Not Found

The specified clientId does not exist or does not belong to the caller's organization.

Example request

curl --request POST \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "GitHub Actions",
    "description": "Used for GitHub Actions CI/CD pipeline",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main"
  }'
curl --request POST \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "GitHub Actions",
    "description": "Used for GitHub Actions CI/CD pipeline",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main"
  }'

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions",
  "description": "Used for GitHub Actions CI/CD pipeline",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-01T10:00:00Z"
}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions",
  "description": "Used for GitHub Actions CI/CD pipeline",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-01T10:00:00Z"
}

Get a federated credential

Retrieve a specific federated credential by its ID.

API endpoint

GET {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}

Path parameters

Parameter	Description
`partitionGlobalId`	The organization global ID.
`clientId`	The ID of the OAuth external application.
`credentialId`	The ID of the federated credential.

Scopes

Requires either one of the following scopes:

PM.OAuthApp
PM.OAuthApp.Read

Request headers

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

Responses

200 OK

Returns the FederatedCredentialDto object for the requested credential.

404 Not Found

The specified credential or application does not exist in the caller's organization.

Example request

curl --request GET \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}'
curl --request GET \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}'

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions",
  "description": "Used for GitHub Actions CI/CD pipeline",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-15T08:30:00Z"
}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions",
  "description": "Used for GitHub Actions CI/CD pipeline",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-15T08:30:00Z"
}

Update a federated credential

Update an existing federated credential. All required fields must be included in the request body.

API endpoint

PUT {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}

Path parameters

Parameter	Description
`partitionGlobalId`	The organization global ID.
`clientId`	The ID of the OAuth external application.
`credentialId`	The ID of the federated credential to update.

Scopes

Requires either one of the following scopes:

PM.OAuthApp
PM.OAuthApp.Write

Request headers

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

Request body

{
  "name": "azure-production-workload-updated",
  "description": "Updated description",
  "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "audience": "api://uipath-production",
  "subject": "00000000-0000-0000-0000-000000000000"
}
{
  "name": "azure-production-workload-updated",
  "description": "Updated description",
  "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
  "audience": "api://uipath-production",
  "subject": "00000000-0000-0000-0000-000000000000"
}

Field	Required	Description
`name`	Yes	A descriptive name for the credential. Must be unique within the application. Maximum 128 characters.
`description`	No	Optional context for the credential. Maximum 512 characters.
`issuer`	Yes	The HTTPS URI of the external identity provider. Must be reachable at create time.
`audience`	Yes	A single string that must appear in the JWT `aud` claim.
`subject`	Yes	A value that must exactly match the JWT `sub` claim.

Responses

200 OK

Returns the updated FederatedCredentialDto object.

400 Bad Request

Validation failed. Possible causes: duplicate name, invalid issuer URI, or unreachable JWKS endpoint.

Example request

curl --request PUT \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "GitHub Actions — Production",
    "description": "Production branch deployments only",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main"
  }'
curl --request PUT \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "GitHub Actions — Production",
    "description": "Production branch deployments only",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://cloud.uipath.com/myorg",
    "subject": "repo:myorg/myrepo:ref:refs/heads/main"
  }'

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions — Production",
  "description": "Production branch deployments only",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-20T14:00:00Z"
}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "1539a53a-e34f-4803-adef-b9cd82f18858",
  "name": "GitHub Actions — Production",
  "description": "Production branch deployments only",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://cloud.uipath.com/myorg",
  "subject": "repo:myorg/myrepo:ref:refs/heads/main",
  "createdAt": "2026-03-01T10:00:00Z",
  "updatedAt": "2026-03-20T14:00:00Z"
}

Delete a federated credential

Delete a federated credential. This action is permanent and immediately invalidates any token acquisition using this credential.

Warning:

Deletion is permanent. After deletion, the credential can no longer be used to acquire new access tokens. Access tokens already issued before deletion remain valid until they expire.

API endpoint

DELETE {accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}

Path parameters

Parameter	Description
`partitionGlobalId`	The organization global ID.
`clientId`	The ID of the OAuth external application.
`credentialId`	The ID of the federated credential to delete.

Scopes

Requires either one of the following scopes:

PM.OAuthApp
PM.OAuthApp.Write

Request headers

--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {access_token}'
--header 'Content-Type: application/json'

Responses

204 No Content

The federated credential was deleted successfully. The response body is empty.

404 Not Found

The specified credential or application does not exist in the caller's organization.

Example request

curl --request DELETE \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}'
curl --request DELETE \
  '{accessURL}/identity_/api/ExternalClient/{partitionGlobalId}/{clientId}/FederatedCredentials/{credentialId}' \
  --header 'Authorization: Bearer {access_token}'

Acquire a token using a federated credential

Exchange a JWT from your external identity provider for a UiPath access token.

API endpoint

POST {accessURL}/identity_/connect/token

Request headers

--header 'Content-Type: application/x-www-form-urlencoded'
--header 'Content-Type: application/x-www-form-urlencoded'

Request body

grant_type=client_credentials
&client_id={client_id}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={jwt_token}
&scope={requested_scopes}
grant_type=client_credentials
&client_id={client_id}
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={jwt_token}
&scope={requested_scopes}

Parameter	Description
`grant_type`	Must be `client_credentials`.
`client_id`	The client ID of the registered OAuth external application.
`client_assertion_type`	Must be `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
`client_assertion`	The JWT issued by your external identity provider.
`scope`	The OAuth scopes requested for the access token.

Responses

200 OK

Returns an access token object. Use the access_token value in the Authorization: Bearer header of subsequent API calls.

400 Bad Request

Token acquisition failed. Possible causes: JWT signature invalid, issuer or audience mismatch, subject mismatch, expired JWT, or JWT exceeds 8 KB.

Schemas

FederatedCredentialDto

The object returned by GET, POST, and PUT operations.

Property	Type	Nullable	Description
`id`	string (uuid)	No	The unique identifier of the federated credential.
`clientId`	string	Yes	The application ID of the OAuth external application this credential belongs to.
`name`	string	Yes	The display name of the federated credential.
`description`	string	Yes	The description of the federated credential.
`issuer`	string	Yes	The URL of the external identity provider.
`audience`	string	Yes	The expected `aud` claim value in the JWT.
`subject`	string	Yes	The expected `sub` claim value in the JWT.
`createdAt`	string (date-time)	No	The UTC timestamp when the credential was created.
`updatedAt`	string (date-time)	No	The UTC timestamp when the credential was last updated.

On this page

List federated credentials
API endpoint
Path parameters
Scopes
Request headers
Responses
Example request
Example response
Create a federated credential
API endpoint
Path parameters
Scopes
Request headers
Request body
Responses
Example request
Example response
Get a federated credential
API endpoint
Path parameters
Scopes
Request headers
Responses
Example request
Example response
Update a federated credential
API endpoint
Path parameters
Scopes
Request headers
Request body
Responses
Example request
Example response
Delete a federated credential
API endpoint
Path parameters
Scopes
Request headers
Responses
Example request
Acquire a token using a federated credential
API endpoint
Request headers
Request body
Responses
Schemas
FederatedCredentialDto

Was this page helpful?

PREVIOUSExternal client

NEXTGroups

List federated credentials​

API endpoint​

Path parameters​

Scopes​

Request headers​

Responses​

200 OK​

Example request​

Example response​

Create a federated credential​

API endpoint​

Path parameters​

Scopes​

Request headers​

Request body​

Responses​

201 Created​

400 Bad Request​

404 Not Found​

Example request​

Example response​

Get a federated credential​

API endpoint​

Path parameters​

Scopes​

Request headers​

Responses​

200 OK​

404 Not Found​

Example request​

Example response​

Update a federated credential​

API endpoint​

Path parameters​

Scopes​

Request headers​

Request body​

Responses​

200 OK​

400 Bad Request​

Example request​

Example response​

Delete a federated credential​

API endpoint​

Path parameters​

Scopes​

Request headers​

Responses​

204 No Content​

404 Not Found​

Example request​

Acquire a token using a federated credential​

API endpoint​

Request headers​

Request body​

Responses​

200 OK​

400 Bad Request​

Schemas​

FederatedCredentialDto​

Was this page helpful?

List federated credentials

API endpoint

Path parameters

Scopes

Request headers

Responses

200 OK

Example request

Example response

Create a federated credential

API endpoint

Path parameters

Scopes

Request headers

Request body

Responses

201 Created

400 Bad Request

404 Not Found

Example request

Example response

Get a federated credential

API endpoint

Path parameters

Scopes

Request headers

Responses

200 OK

404 Not Found

Example request

Example response

Update a federated credential

API endpoint

Path parameters

Scopes

Request headers

Request body

Responses

200 OK

400 Bad Request

Example request

Example response

Delete a federated credential

API endpoint

Path parameters

Scopes

Request headers

Responses

204 No Content

404 Not Found

Example request

Acquire a token using a federated credential

API endpoint

Request headers

Request body

Responses

200 OK

400 Bad Request

Schemas

FederatedCredentialDto