Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/api-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,23 @@ one from the CLI, or reuse the UUID supplied with `--idempotency-key`.
| `POST /v1/gateway/describe` | `connections describe ID TOOL` |
| `POST /v1/gateway/call` | `connections call ID TOOL --arguments JSON` |
| `POST /mcp` (JSON-RPC `tools/list`) | `mcp tools [NAME]` |
| `GET /v1/identities` | `identities list` |
| `POST /v1/identities` | `identities create --data JSON` |
| `GET /v1/identities/{id}` | `identities get IDENTITY`, `identities permissions IDENTITY` |
| `PUT /v1/identities/{id}` | `identities update`, `enable`, `disable`, `permissions --allow/--deny` |
| `DELETE /v1/identities/{id}` | `identities delete IDENTITY` |
| `PUT /v1/identities/{id}/grants` | `identities access IDENTITY MEMBER [--assume] [--manage]` |
| `PUT /v1/identities/{id}/accounts/{connectionId}` | `identities account IDENTITY CONNECTION_ID` |
| `GET /v1/identities/{id}/sessions` | `identities sessions list IDENTITY` |
| `POST /v1/identities/{id}/sessions` | `identities sessions start IDENTITY --label LABEL` |
| `DELETE /v1/identities/{id}/sessions/{sessionId}` | `identities sessions revoke IDENTITY SESSION_ID` |

Identity routes come from platform `640c00b`.
Identity commands resolve names with `GET /v1/identities` and member emails with
`/v1/auth/organization/list-members`, because identity routes accept only full IDs.
Updates read the identity first and send its whole configuration with the change.
To compare supplied grants, they look up your member ID with `/v1/whoami` and a member list
filtered by your user ID.

Auth commands use `/v1/auth/device/code`, `/device/token`, `/get-session`, and `/sign-out`.
Organization commands use Better Auth's `/v1/auth/organization/*` routes; organization
Expand Down
112 changes: 112 additions & 0 deletions docs/cli-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ For example, use `adapt org members ls` or `adapt sandbox ls --all`.
| `registry` | `list`, `create`, `update`, `delete` |
| `connections` | `list`, `get`, `create`, `update`, `delete`, `refresh`, `grant`, `oauth`, `oauth-complete`, `calls`, `principals`, `search`, `describe`, `call` |
| `keys` | `list`, `create`, `delete` |
| `identities` | `list`, `get`, `create`, `update`, `enable`, `disable`, `delete`, `permissions`, `access`, `account` |
| `identities sessions` | `list`, `start`, `revoke` |
| `sessions` | `list`, `revoke`, `revoke-others` |
| `mcp` | `list`, `revoke`, `tools` |
| `events` | Show organization changes, or personal changes with `--personal` |
Expand Down Expand Up @@ -376,6 +378,7 @@ The Platform API must support resource ID prefixes.

Authentication and organization commands require exact identifiers.
This includes `--org`, members, invitations, keys, sessions, and grant principals.
Identity commands accept a full identity ID or an exact identity name; see [Identities](#identities).
`org use` accepts a full organization ID or an exact slug.
Pagination cursors, idempotency keys, and credential tokens also require exact values.

Expand Down Expand Up @@ -517,6 +520,115 @@ To revoke the key, use `adapt keys delete KEY_ID`.
Logout always uses the saved credential.
It never revokes a key from `ADAPT_TOKEN`.

## Identities

An identity is a set of permissions, tools, and secrets that members assume through expiring sessions.
Identity commands use your browser sign-in.
Platform refuses them for API keys and identity tokens.

```sh
adapt identities list
adapt identities create --name deploy-bot --allow sandboxes:write --allow commands:write --max-session 1800
adapt identities create --data @identity.json
adapt identities get deploy-bot
adapt identities update deploy-bot --data '{"maxSessionSeconds":7200}'
adapt identities disable deploy-bot
adapt identities enable deploy-bot
adapt identities delete deploy-bot
```

`create` builds the request from `--data` and then its options, which override fields in the JSON.
Permissions start empty, and `--allow` adds actions as in [Permissions](#permissions).
Use `--data` for connections, secrets, and member access.
Only organization owners and admins can create identities, and the creator can assume and manage the new identity.

Commands accept a full identity ID or an exact name.
Names match without case sensitivity.
The CLI looks names up among the identities that you can assume or manage.

`update` changes only the fields in its JSON and keeps the others.
A top-level field replaces its whole value, so `permissions` replaces every resource's actions.
Include `version` to refuse the change if the identity has changed since you read it.
Supplied `grants` set every other member's access; Platform keeps your own.
The CLI compares them by each member's access, so applying the same list again saves nothing.
`enable` and `disable` change only `enabled`.

Platform ends an identity's active sessions when its settings, permissions, or member access change.
Changing your account choice ends your own sessions.
If a command would leave every setting as it is, the CLI does not save, and sessions continue.

Platform checks the identity's connections again on every save.
If a connection was removed or its allowed tools changed, every save fails until `update` supplies corrected `connections`.
This includes `disable`.
`delete` still works.

### Permissions

An identity's sessions can read, write, or use each resource:

| Resource | Actions |
| --- | --- |
| `sandboxes`, `commands`, `volumes` | `read`, `write` |
| `images`, `endpoints`, `registries`, `models` | `read`, `write`, `use` |
| `mcp-tools`, `secrets` | `read`, `use` |

```sh
adapt identities permissions deploy-bot
adapt identities permissions deploy-bot --allow sandboxes:write --allow images:use --deny volumes:write
```

API names such as `execs`, `ingresses`, and `registryCredentials` also work.
Allowing `write` or `use` also allows `read`.
You can deny `read` separately afterward.
Platform refuses permissions beyond your own access.

### Member access

```sh
adapt identities access deploy-bot ana@example.com --assume
adapt identities access deploy-bot MEMBER_ID --assume --manage
adapt identities access deploy-bot ana@example.com
```

`--assume` lets a member start sessions.
`--manage` lets a member change the identity.
Without either option, the command removes the member's access.
If the member already has the requested access, the CLI does not save, and the identity's sessions continue.
Use a member ID from `adapt org members list` or the member's email.
Organization owners and admins can manage every identity.

### Personal accounts

Some connections require each person's own account.
For those connections, choose your personal connection to the same MCP server:

```sh
adapt identities account deploy-bot CONNECTION_ID --use PERSONAL_CONNECTION_ID
adapt identities account deploy-bot CONNECTION_ID --clear
```

Platform never substitutes a shared account.

### Sessions

```sh
adapt identities sessions start deploy-bot --label "nightly deploy" --duration 1800
adapt identities sessions list deploy-bot
adapt identities sessions revoke deploy-bot SESSION_ID
```

`sessions start` prints the session token once in its response.
The CLI never saves it.
Give the token to one process as `ADAPT_TOKEN`; it works with Platform APIs and MCP until it expires or is revoked.
The duration defaults to the identity's maximum session length.
Sessions cannot be extended.

`sessions list` shows your sessions, or every member's sessions if you manage the identity.
`sessions revoke` checks the session list afterward and fails if Platform found no matching session.

When a session expires or is revoked, requests that use its token fail with `401`.
Start a new session to continue.

## Platform MCP tools

Platform hosts an MCP server at `/mcp` on the API origin.
Expand Down
18 changes: 18 additions & 0 deletions skills/adapt/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,24 @@ describe the message-posting tool and use that channel ID. Listing channels is
a separate action from sending a message. Inspect tool results for reported
errors as well as the CLI exit status.

## Identities

```sh
adapt identities list
adapt identities create --name NAME --allow sandboxes:write --allow commands:write
adapt identities permissions IDENTITY
adapt identities sessions start IDENTITY --label "LABEL" --duration 1800
```

Identities are organization-owned sets of permissions, tools, and secrets.
Identity commands need the user's browser sign-in, not an API key. IDENTITY is
a full ID or an exact name. `update --data` changes only the fields given;
`permissions --allow RESOURCE:ACTION` and `--deny` change single actions (read,
write, use). Any change to an identity ends its active sessions. `sessions
start` prints a token once: pass it only to the process that needs it as
`ADAPT_TOKEN`, and never print or store it. An expired or revoked identity
session returns 401; start a new session rather than signing in again.

## Platform MCP server

```sh
Expand Down
19 changes: 18 additions & 1 deletion src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -278,8 +278,25 @@ impl fmt::Display for ApiError {
if let Some(retry) = &self.retry_after {
write!(f, "; retry after {}", output::safe(retry))?;
}
// Identity tokens come from a session, not a login, so signing in again won't help.
// Only Platform's identity-token errors start this way; other messages may
// mention identity sessions in passing.
let identity_session = self.message.starts_with("This identity session");
if self.status == StatusCode::UNAUTHORIZED {
write!(f, "; run `adapt auth login` to sign in again")?;
if identity_session {
write!(
f,
"; start a new one with `adapt identities sessions start`"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Explain how to clear the expired token override

With exported ADAPT_TOKEN, the recommended session-start command reuses the expired token and returns the same 401. Tell users to unset the override before issuing with their saved browser login.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Explain how to clear the expired token override

With exported ADAPT_TOKEN, the recommended session-start command reuses the expired token and returns the same 401. Tell users to unset the override before issuing with their saved browser login.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Explain how to clear the expired token override

With exported ADAPT_TOKEN, the recommended session-start command reuses the expired token and returns the same 401. Tell users to unset the override before issuing with their saved browser login.

)?;
} else {
write!(f, "; run `adapt auth login` to sign in again")?;
}
}
if self.status == StatusCode::FORBIDDEN && identity_session {
write!(
f,
"; an identity session works only in its own organization, so remove --org or ADAPT_ORG_ID"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Account for the saved organization in the 403 hint

Removing --org/ADAPT_ORG_ID restores the profile's saved organization, which can produce the same 403. Recommend explicitly selecting the identity's organization instead. Reproduced with a saved profile.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Account for the saved organization in the 403 hint

Removing --org/ADAPT_ORG_ID restores the profile's saved organization, which can produce the same 403. Recommend explicitly selecting the identity's organization instead. Reproduced with a saved profile.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Account for the saved organization in the 403 hint

Removing --org/ADAPT_ORG_ID restores the profile's saved organization, which can produce the same 403. Recommend explicitly selecting the identity's organization instead.

)?;
}
if self.code == "ORGANIZATION_REQUIRED" {
write!(f, "; run `adapt org list` then `adapt org use ID`")?;
Expand Down
149 changes: 147 additions & 2 deletions src/cli.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
use crate::input::{ResourceRef, image_name, pair, search_text};
use crate::input::{
ResourceRef, identity_name, identity_ref, image_name, pair, search_text, session_label,
};
use clap::{Args, Parser, Subcommand, ValueEnum};
use std::path::PathBuf;
use uuid::Uuid;
Expand All @@ -8,7 +10,7 @@ use uuid::Uuid;
name = "adapt",
version,
about = "Adapt Platform CLI",
after_help = "Start here: adapt auth login\nUse --json for scripting. Run any command with --help for details.\nCore resource IDs accept full UUIDs or unambiguous hexadecimal prefixes. Auth and organization IDs require full UUIDs."
after_help = "Start here: adapt auth login\nUse --json for scripting. Run any command with --help for details.\nCore resource IDs accept full UUIDs or unambiguous hexadecimal prefixes. Identities accept a full UUID or exact name. Auth and organization IDs require full UUIDs."
)]
pub struct Cli {
/// Saved connection profile
Expand Down Expand Up @@ -78,6 +80,9 @@ pub enum Command {
/// Manage organization API keys
#[command(subcommand)]
Keys(KeyCommand),
/// Manage identities: scoped permissions, tools, and sessions for people and agents
#[command(subcommand, visible_alias = "identity")]
Identities(IdentityCommand),
/// Manage your browser and CLI sessions
#[command(subcommand)]
Sessions(SessionCommand),
Expand Down Expand Up @@ -678,6 +683,146 @@ pub enum KeyCommand {
},
}

#[derive(Subcommand)]
#[command(
after_help = "IDENTITY is a full ID or an exact identity name (ignoring case).\nIdentity commands use your browser sign-in; API keys and identity tokens cannot manage or assume identities.\nChanging an identity's settings, permissions, or member access ends its active sessions."
)]
pub enum IdentityCommand {
/// List identities you can assume or manage
#[command(visible_alias = "ls")]
List(Page),
/// Show an identity's configuration, member access, and your account bindings
Get {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
},
/// Create an identity from flags, JSON, or both; you get assume and manage access
#[command(
after_help = "Flags override fields in --data. Permissions start empty; add actions with --allow.\nJSON fields: name, permissions, description, enabled, connections, environmentVariableSetIds, maxSessionSeconds, grants.\nOnly organization owners and admins can create identities."
)]
Create(IdentityCreate),
/// Change only the fields in the JSON; other fields keep their current values
#[command(
after_help = "Top-level fields replace the current value whole, so `permissions` replaces every resource.\nUse `adapt identities permissions` to change single actions.\nOmit `version` to update the current version; include it to refuse a stale edit."
)]
Update {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
#[command(flatten)]
data: Data,
},
/// Allow new sessions
Enable {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
},
/// Block new sessions and end active ones
Disable {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
},
/// Delete an identity and end its sessions
Delete {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
},
/// Show or change what the identity's sessions can do: Read, Write, or Use per resource
#[command(
after_help = "Resources: sandboxes, commands, volumes (read, write); images, endpoints, registries, models (read, write, use); mcp-tools, secrets (read, use).\nAPI names such as execs or ingresses also work. Allowing write or use also allows read."
)]
Permissions {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
/// Add an action, e.g. sandboxes:write (repeatable)
#[arg(long, value_name = "RESOURCE:ACTION", value_parser = crate::identities::permission)]
allow: Vec<crate::identities::Permission>,
/// Remove an action, e.g. volumes:write (repeatable)
#[arg(long, value_name = "RESOURCE:ACTION", value_parser = crate::identities::permission)]
deny: Vec<crate::identities::Permission>,
},
/// Set a member's access to the identity; with neither flag, removes it
Access {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
/// Member ID from `adapt org members list`, or the member's email
member: String,
/// Allow the member to start sessions as this identity
#[arg(long)]
assume: bool,
/// Allow the member to change this identity
#[arg(long)]
manage: bool,
},
/// Choose your personal account for a connection that uses personal accounts
Account {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
/// The identity's organization connection ID
connection: Uuid,
/// Your personal connection to the same MCP server
#[arg(
long = "use",
value_name = "PERSONAL_CONNECTION_ID",
required_unless_present = "clear",
conflicts_with = "clear"
)]
account: Option<Uuid>,
/// Remove your account choice
#[arg(long)]
clear: bool,
},
/// Start, list, and revoke identity sessions
#[command(subcommand)]
Sessions(IdentitySessionCommand),
}

#[derive(Args)]
pub struct IdentityCreate {
/// Unique in the organization, ignoring case
#[arg(long, value_parser = identity_name, required_unless_present = "data")]
pub name: Option<String>,
#[arg(long)]
pub description: Option<String>,
/// Allow an action, e.g. sandboxes:write (repeatable); write and use also allow read
#[arg(long, value_name = "RESOURCE:ACTION", value_parser = crate::identities::permission)]
pub allow: Vec<crate::identities::Permission>,
/// Longest session in seconds; Platform's default is 3600
#[arg(long, value_name = "SECONDS", value_parser = clap::value_parser!(u32).range(300..=86400))]
pub max_session: Option<u32>,
/// Request JSON: inline, @file.json, or - for stdin
#[arg(long, short = 'd')]
pub data: Option<String>,
}

#[derive(Subcommand)]
pub enum IdentitySessionCommand {
/// List sessions: yours, or everyone's if you manage the identity
#[command(visible_alias = "ls")]
List {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
#[command(flatten)]
page: Page,
},
/// Start a session and print its token once; the token is never saved
Start {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
/// Shown to identity managers in session lists
#[arg(long, value_parser = session_label)]
label: String,
/// Lifetime in seconds; defaults to the identity's maximum
#[arg(long, value_name = "SECONDS", value_parser = clap::value_parser!(u32).range(300..=86400))]
duration: Option<u32>,
},
/// Revoke a session
Revoke {
#[arg(value_name = "IDENTITY", value_parser = identity_ref)]
identity: String,
session: Uuid,
},
}

#[derive(Subcommand)]
pub enum SessionCommand {
#[command(visible_alias = "ls")]
Expand Down
3 changes: 2 additions & 1 deletion src/commands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ use crate::{
auth,
cli::*,
config::{self, Config, Credential, CredentialKind},
input, mcp, output, shell, skill, stream,
identities, input, mcp, output, shell, skill, stream,
};
use anyhow::{Context, Result, bail};
use clap::ValueEnum;
Expand Down Expand Up @@ -186,6 +186,7 @@ pub async fn run(cli: Cli) -> Result<u8> {
},
Command::Connections(command) => connections(&api, command).await?,
Command::Keys(command) => keys(&api, command).await?,
Command::Identities(command) => return identities::run(&api, command, cli.json).await,
Command::Sessions(command) => match command {
SessionCommand::List => api.get("/v1/auth/sessions").await?,
SessionCommand::Revoke { id } => api.post("/v1/auth/sessions/revoke", &json!({"id":id.to_string()})).await?,
Expand Down
Loading
Loading