API Tara: account
Account and access tokens
This page is generated from
openapi.yamlbynpm run gen, so do not edit it by hand. Authentication is described on the overview page.
/v1/apps/delegationMint a read-only delegation token for a user of an organization (app service account)
For web apps of the platform (Bandum) that sign users in through Tara. The caller is an API token with the delegate scope (only tara-admin or the install script can grant it; the Portal cannot). Tara signs a tara_dlg_… token for exactly this user and organization, valid for a few minutes, only if the user is a member of the organization now (otherwise 404, nothing is revealed). The token is read-only and works for GET /v1/me, GET /v1/orgs/{org}, GET /v1/orgs/{org}/projects and GET /v1/orgs/{org}/members (the team directory, never with emails); every other route answers 403. Each token is written to the organization's audit log (actor = the service account). Rate limit per caller: 429.
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
user | string | yes | Tara user id (uuid) |
org | string | yes | Organization slug |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Delegation token | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | The token has no delegate scope | application/problem+json · object |
| 404 | The user is not a member of the organization (or it does not exist) | application/problem+json · object |
| 429 | Too many requests | application/problem+json · object |
| 503 | Delegation tokens are not configured (TARA_DELEGATION_KEY) | application/problem+json · object |
Example response
{
"token": "tara_dlg_…",
"expiresAt": "2026-11-01T00:00:00Z"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/apps/delegation" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user":"string","org":"string"}'/v1/meThe signed-in user
Responses
| Code | Description | Type |
|---|---|---|
| 200 | User information | application/json · object |
| 401 | Not signed in | application/problem+json · object |
Example response
{
"id": "string",
"login": "string",
"namespace": "string",
"name": "string",
"avatarUrl": "string",
"memberships": [
{
"org": "string",
"role": "owner"
}
],
"orgs": [
{
"slug": "acme",
"name": "Acme Inc.",
"plan": "free",
"platform": false,
"role": "owner"
}
],
"pendingInvites": [
{
"id": "string",
"org": {},
"role": "admin",
"invitedBy": "string",
"expiresAt": "2026-11-01T00:00:00Z"
}
],
"canCreateOrg": false,
"permissions": {
"publishOrgs": [
"string"
],
"org": "string",
"role": "owner",
"tokenScopes": [
"string"
]
}
}Call with curl
curl "https://tara.phillipcli.cloud/v1/me" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/meDelete my account (from a Portal or CLI session only; a token cannot)
Send {"confirm": "<your login>"}. Refused with 409 sole_owner while you are the only owner of an organization that still has other members (the body lists them: hand over ownership or delete the organization first). Otherwise sessions, tokens, sign-in identities, tracker identities, memberships and pending invitations addressed to you are removed; your private personal resources are deleted and your public community resources move to the anonymous owner deleted-<hash8>; your older audit entries keep the row but show the anonymous actor and lose login and email from their details. Organizations where you were the only member go through the organization deletion grace period. Device and SCIM tokens you created keep working. Ryoma replaces your login with deleted-<hash8> afterwards (retried until it succeeds).
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
confirm | string | yes | Your login |
Responses
| Code | Description | Type |
|---|---|---|
| 204 | The account was deleted | |
| 400 | The confirmation does not match your login | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Not a Portal or CLI session | application/problem+json · object |
| 409 | You are the only owner of an organization that still has other members (code sole_owner) | application/problem+json · object |
Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/me" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"confirm":"string"}'/v1/me/tokensMy active access tokens
Responses
| Code | Description | Type |
|---|---|---|
| 200 | List of tokens (token values are not included) | application/json · object |
| 401 | Not signed in | application/problem+json · object |
Example response
{
"items": [
{
"id": "string",
"name": "string",
"prefix": "string",
"scopes": [],
"createdAt": "2026-11-01T00:00:00Z",
"expiresAt": "2026-11-01T00:00:00Z"
}
]
}Call with curl
curl "https://tara.phillipcli.cloud/v1/me/tokens" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/me/tokensCreate an access token (from a Portal session only)
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
scopes | read | publish[] | Defaults to read | |
lifetimeDays | integer | ||
org | string | Slug of the organization the token is bound to (default the current one; 409 no_org if the user has none) |
Responses
| Code | Description | Type |
|---|---|---|
| 201 | New token. The secret value is returned only once. | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | The organization in the request is not one of the user's | application/problem+json · object |
| 409 | Conflict: too many tokens, or the user has no organization yet (no_org) | application/problem+json · object |
Example response
{
"token": {
"id": "string",
"name": "string",
"prefix": "string",
"scopes": [
"read"
],
"createdAt": "2026-11-01T00:00:00Z",
"expiresAt": "2026-11-01T00:00:00Z"
},
"secret": "string"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/me/tokens" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Phillip on my laptop","scopes":["read"],"lifetimeDays":90,"org":"string"}'/v1/me/tokens/{id}Revoke a token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 204 | Revoked | |
| 401 | Not signed in | application/problem+json · object |
| 404 | Not found | application/problem+json · object |
Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/me/tokens/<id>" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/me/tracker-identitiesMy identities in task trackers
Responses
| Code | Description | Type |
|---|---|---|
| 200 | My identities | application/json · object[] |
| 401 | Not signed in | application/problem+json · object |
Example response
[
{
"baseUrl": "https://acme.atlassian.net",
"identity": "5b10ac8d82e05b22cc7d4ef5"
}
]Call with curl
curl "https://tara.phillipcli.cloud/v1/me/tracker-identities" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/me/tracker-identitiesSave who I am in a tracker (`ph connect jira` sends it)
One identity per (baseUrl, user); saving again replaces it. Each (baseUrl, identity) pair belongs to one user: 409 identity_taken when someone else already has it. Tara does not check the identity with the tracker.
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
baseUrl | string | yes | |
identity | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 200 | Saved | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 409 | The pair belongs to another user (identity_taken) | application/problem+json · object |
Example response
{
"baseUrl": "https://acme.atlassian.net",
"identity": "5b10ac8d82e05b22cc7d4ef5"
}Call with curl
curl -X PUT "https://tara.phillipcli.cloud/v1/me/tracker-identities" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"baseUrl":"https://acme.atlassian.net","identity":"5b10ac8d82e05b22cc7d4ef5"}'/v1/me/tracker-identitiesRemove my identity for a tracker
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
baseUrl | query | string | yes |
Responses
| Code | Description | Type |
|---|---|---|
| 204 | Removed (also when there was none) | |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
Call with curl
curl -X DELETE "https://tara.phillipcli.cloud/v1/me/tracker-identities?baseUrl=string" \
-H "Authorization: Bearer $TARA_TOKEN"/v1/cli/codesIssue a one-time code for CLI sign-in (from a Portal session only, after the user confirms)
Phillip opens the browser at /auth/cli/start, Tara redirects to the Portal confirmation page; the Portal calls this endpoint and then redirects the browser to Phillip's loopback port. Phillip exchanges the code with the verifier (PKCE S256) for a CLI session at POST /auth/cli/token. The code lives for 2 minutes and is single-use. Platform web apps (Bandum…) start at /auth/app/start?app=…; a code issued for an app can only be exchanged for an identity at POST /auth/app/token, not for a Tara session.
Body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
challenge | string | yes | base64url(SHA-256(verifier)) |
app | string | Platform web app signing in through Tara (TARA_APPS); leave empty for Phillip | |
org | string | Slug of the organization chosen for the CLI session (omit to let the CLI choose when it exchanges the code) |
Responses
| Code | Description | Type |
|---|---|---|
| 201 | One-time code | application/json · object |
| 400 | Invalid input | application/problem+json · object |
| 401 | Not signed in | application/problem+json · object |
| 403 | Forbidden | application/problem+json · object |
| 404 | The organization in the request is not one of the user's | application/problem+json · object |
Example response
{
"code": "string",
"expiresAt": "2026-11-01T00:00:00Z",
"callback": "string"
}Call with curl
curl -X POST "https://tara.phillipcli.cloud/v1/cli/codes" \
-H "Authorization: Bearer $TARA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"challenge":"string","app":"string","org":"string"}'