> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/integrations/external-integrations.md).

# External Integrations

External integration credentials let you grant third-party systems scoped access to create external user sessions on behalf of your workspace. Each credential is bound to a specific integration and restricted to a set of services, so the third party can only create sessions for the services you explicitly allow.

This is useful when you want an external system - such as a partner scheduling platform or a customer portal - to initiate conversations with your agent without giving it full service account privileges.

## Key Concepts

* **Integration-scoped.** Each credential belongs to a specific integration in your workspace.
* **Service-restricted.** The credential includes a list of service IDs. It can only create external user sessions for those services.
* **Rotatable.** You can rotate the client secret without changing the credential ID or client ID. The previous secret is immediately invalidated.
* **Revocable.** Revoking a credential permanently disables it. Revoked credentials cannot authenticate or create sessions.
* **One-time secret.** The client secret is returned only at creation and rotation. Store it securely - it cannot be retrieved later.

## Endpoints

### Create Credential

Creates a new external integration credential and returns the client ID and client secret. The client secret is only returned once - store it securely.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/external-integrations/{integration\_id}/credentials" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### List Credentials

Returns all external integration credentials for the specified integration, ordered by creation time (newest first). Listed credentials never include the `client_secret`.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/external-integrations/{integration\_id}/credentials" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Rotate Credential

Generates a new client secret for an existing credential. The previous secret is immediately invalidated. The credential ID and client ID remain unchanged.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/external-integrations/{integration\_id}/credentials/{credential\_id}/rotate" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Revoke Credential

Permanently disables a credential. Revoked credentials cannot be used to authenticate or create sessions. This action cannot be undone.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/external-integrations/{integration\_id}/credentials/{credential\_id}" method="delete" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Authentication Flow

Once you have a credential, use it to obtain access tokens and create external user sessions:

1. **Obtain an access token.** Use the `client_credentials` grant type with the credential's `client_id` and `client_secret`. The returned token has the `external_user_sessions:create` scope.
2. **Create an external user session.** Use the access token as the parent token in an `external_user_session` grant request. Specify a `service_id` from the credential's allowed service list, along with the `workspace_id`, `external_subject_key`, and optional `consumer_entity_id`.

The `service_id` must be in the credential's allowlist. Requests for services not in the list are rejected with a 403 error.

External integration tokens are exempt from IP allowlist checks and MFA enforcement.

If the resulting external-user session will call customer APIs that require per-user token exchange, include a verified `external_subject_key` when creating the session and bind it into the Platform Integration auth config. See [External User Subject-Key Binding](/developer-guide/platform-api/integrations/external-user-subject-key-binding.md).

## Permissions

All credential management endpoints require:

* External integration update permission (`ExternalIntegration.update`)
* API key create permission
* API key delete permission

These endpoints also require an admin or owner role - the role check is enforced at the route, in addition to the permission checks.

## Comparison with Service Accounts

| Capability                    | Service Account | External Integration Credential      |
| ----------------------------- | --------------- | ------------------------------------ |
| Create external user sessions | No              | Yes, only for allowed services       |
| Service restriction           | No              | Yes, scoped to a service allowlist   |
| Integration binding           | No              | Yes, bound to a specific integration |
| IP allowlist enforcement      | Exempt          | Exempt                               |
| MFA enforcement               | Exempt          | Exempt                               |
| Secret rotation               | Supported       | Supported                            |
| Revocation                    | Supported       | Supported                            |

External integration credentials are the only credential type that can create external user sessions - the parent token in an `external_user_session` grant must be an external integration principal, and requests with any other parent token type are rejected with a 403 error. Use them to grant a third-party system the minimum access needed to create user sessions for specific services, without exposing broader service account capabilities.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/integrations/external-integrations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.