# External client — Federated credentials

> 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.

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](https://docs.uipath.com/test-cloud/automation-cloud/latest/admin-guide/managing-external-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'
```

:::note
To obtain the `{access_token}`, use an organization administrator token or authenticate through one of the methods described in [Authentication methods](https://docs.uipath.com/test-cloud/automation-cloud/latest/api-guide/authentication-methods).
:::

### Responses

#### 200 OK

Returns an array of [FederatedCredentialDto](#federatedcredentialdto) objects. Returns an empty array if no credentials are registered.

### Example request

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

### Example response

```json
[
  {
    "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'
```

### Request body

```json
{
  "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](#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

```bash
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

```json
{
  "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'
```

### Responses

#### 200 OK

Returns the [FederatedCredentialDto](#federatedcredentialdto) object for the requested credential.

#### 404 Not Found

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

### Example request

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

### Example response

```json
{
  "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'
```

### Request body

```json
{
  "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](#federatedcredentialdto) object.

#### 400 Bad Request

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

### Example request

```bash
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

```json
{
  "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'
```

### 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

```bash
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'
```

### 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}
```

| 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. |