---
title: "Exchange a workspace identity for an API token or a connector credential [identity]"
method: POST
path: "/workspace-identity/exchange"
tags: ["workspace-identity"]
---

# Exchange a workspace identity for an API token or a connector credential \[identity\]

`POST /workspace-identity/exchange`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/workspace-identity/exchange`
- Auth: HTTP bearer

Bearer wid_…. {for: agentsky_api} mints a workspace-fixed ast_ token for the session's owner (read+write, one hour, never past the identity) that reaches the route groups the identity lists and nothing else. {for: connector, kind} attaches the vault the connector names for the identity's role to the session and pushes its network policy, then answers placeholders by environment variable name: export them and send requests to origin; the real credential is set at the network edge and never reaches the pod. Every exchange is recorded and revoked with the session. 404 connector_not_installed, 403 role_not_granted, 409 connector_misconfigured, 400 egress refusals, 503 connector_attach_failed.

## Request body

- union
  - object
    - `for` 'agentsky_api', required
  - object
    - `for` 'connector', required
    - `kind` string, required: A short lowercase name for the service, e.g. crm
    - `name` string

## Response `201`

Created

- union
  - object
    - `for` 'agentsky_api', required
    - `token` string, required: ast_…; returned only here, limited to the route groups the identity lists
    - `scopes` string[], required
    - `api_base` string, required
    - `expires_at` string, date-time, required
  - object
    - `for` 'connector', required
    - `kind` string, required
    - `name` string, required
    - `origin` string, required
    - `env` object, required: Placeholders by environment variable name; the platform sets the real credential toward origin at the network edge
    - `mcp_servers` object[], required: MCP servers the vault's bearer secrets reach; the platform sets Authorization on every request to each, so connect without a token
      - `url` string
    - `expires_at` string, date-time, required

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/workspace-identity/exchange/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)