openapi: 3.0.0
info:
description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
title: ArchAstro Platform Activity Feed auth API
version: v1
tags:
- name: auth
paths:
/api/v1/auth/allowed_auth_methods:
get:
description: 'Returns the complete catalogue of authentication methods the platform supports,
including each method''s stable slug, user-facing name, and description.
Use this endpoint to render method labels in sign-in UIs or org settings screens
without hardcoding copy or maintaining your own enum list. Results reflect the
platform''s source-of-truth catalogue and are consistent across all orgs.
This endpoint requires only a publishable key and is accessible without an active
user session, making it suitable for pre-authentication flows such as login page
rendering or onboarding configuration.'
operationId: get_api_v1_auth_allowed_auth_methods
parameters: []
responses:
'200':
content:
application/json:
schema:
description: Catalogue of all authentication methods the platform supports.
example:
data:
- description: An example description.
name: Example Name
slug: example-slug
properties:
data:
description: Ordered array of supported auth method objects, each with a stable slug, display name, and description.
example:
- description: An example description.
name: Example Name
slug: example-slug
items:
description: A single authentication method supported by the platform, including its stable identifier and user-facing copy.
example:
description: An example description.
name: Example Name
slug: example-slug
properties:
description:
description: One-sentence user-facing explanation of how this auth method works, suitable for display in an auth selection UI.
example: An example description.
type: string
name:
description: Short user-facing label suitable for buttons or list items, e.g. `"Password"` or `"Magic Link"`.
example: Example Name
type: string
slug:
description: Stable machine-readable identifier for this auth method, e.g. `"password"` or `"magic_link"`. Use this value when enabling or referencing auth methods programmatically.
example: example-slug
type: string
required:
- description
- name
- slug
type: object
type: array
required:
- data
type: object
description: Successful response
summary: List supported auth methods
tags:
- auth
x-auth:
- publishable_key
/api/v1/auth/login:
post:
description: 'Authenticates a user with an email address and password and returns a short-lived
access token, a refresh token, and the authenticated user object. Use the refresh
token with the `/auth/refresh` endpoint to obtain new access tokens without
re-authenticating.
Password login must be enabled for the app; apps that have disabled password
authentication return HTTP 403. Requests are rate-limited per IP (10 per minute)
and per email-IP pair (5 per minute) — exceeding either limit returns HTTP 429.'
operationId: post_api_v1_auth_login
parameters: []
requestBody:
content:
application/json:
schema:
example:
email: user@example.com
password: string
properties:
email:
description: Email address of the user to authenticate.
example: user@example.com
type: string
password:
description: Password for the account associated with the given email.
example: string
type: string
required:
- email
- password
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokens'
description: Successful response
'401':
description: Invalid credentials
'403':
description: Password login is not enabled for this organization
'429':
description: Rate limited
summary: Authenticate with email and password
tags:
- auth
x-auth:
- publishable_key
/api/v1/auth/login/link:
post:
description: 'Sends a magic link to the given email address so an existing user can sign in
without a password. The user clicks the link in their email and is redirected to
`redirect_uri` with a token; pass that token to `/auth/verify_link` to obtain
session tokens.
If no account exists for the email, the endpoint still returns success to prevent
email enumeration — no link is sent in that case. Both `email` and `redirect_uri`
are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair
(3 per minute) — exceeding either limit returns HTTP 429. Returns HTTP 204 on success.'
operationId: post_api_v1_auth_login_link
parameters: []
requestBody:
content:
application/json:
schema:
example:
email: user@example.com
redirect_uri: https://example.com
properties:
email:
description: Email address of the account to send the magic link to.
example: user@example.com
type: string
redirect_uri:
description: URL the user is redirected to after clicking the magic link. The token is appended as a query parameter.
example: https://example.com
type: string
type: object
required: true
responses:
'204':
description: No content
'400':
description: Missing email or redirect_uri
'429':
description: Rate limited
summary: Request a magic link for login
tags:
- auth
x-auth:
- publishable_key
x-sdk-name: request_login_magic_link
/api/v1/auth/refresh:
post:
description: 'Exchanges a valid refresh token for a new access token and a new refresh token,
rotating the refresh token on every call. The response also includes the updated
user object. Store the new refresh token and discard the old one.
Refresh tokens are single-use — submitting an already-consumed token returns HTTP 401.
Rate limiting is applied per (user, IP) pair when the token can be verified, and
falls back to IP-only when it cannot. The limit is 30 exchanges per minute per
bucket; exceeding it returns HTTP 429.'
operationId: post_api_v1_auth_refresh
parameters: []
requestBody:
content:
application/json:
schema:
example:
refresh_token: string
properties:
refresh_token:
description: Refresh token previously issued by a login, registration, or token-refresh response.
example: string
type: string
required:
- refresh_token
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokens'
description: Successful response
'401':
description: Invalid or expired refresh token
'429':
description: Rate limited
summary: Refresh an access token
tags:
- auth
x-auth:
- publishable_key
/api/v1/auth/register:
post:
description: "Creates a new user account and returns an access token, refresh token, and the new\nuser object. Two registration paths are supported:\n\n- **Team registration**: supply `team_invite` with a valid team invite ID. The new\n user is added to that team immediately upon registration. Returns HTTP 404 if the\n invite is not found.\n- **Standard registration**: supply `password`. An `invite_code` may optionally be\n included for invite-gated apps; an invalid code returns HTTP 404.\n\nExactly one of `team_invite` or `password` must be provided; omitting both returns\nHTTP 400. Password registration must be enabled for the app; disabled apps return\nHTTP 403. The response status is HTTP 201 on success."
operationId: post_api_v1_auth_register
parameters: []
requestBody:
content:
application/json:
schema:
example:
alias: string
email: user@example.com
full_name: Example Name
invite_code: string
password: string
team_invite: string
timezone: America/New_York
properties:
alias:
description: Display alias (handle) for the new account.
example: string
type: string
email:
description: Email address for the new account.
example: user@example.com
type: string
full_name:
description: Full name for the new account.
example: Example Name
type: string
invite_code:
description: Invite code for invite-gated registration. Applied only in the standard registration path.
example: string
type: string
password:
description: Password for the new account. Required for standard (non-team-invite) registration.
example: string
type: string
team_invite:
description: Team invite ID. When provided, the user is added to the team on registration.
example: string
type: string
timezone:
description: IANA timezone name for the new account, e.g. `"America/New_York"`.
example: America/New_York
type: string
required:
- email
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokens'
description: Successful response
'400':
description: Missing required parameters
'403':
description: Password registration is not enabled for this organization
'404':
description: Team invite not found
'422':
description: Validation failed
summary: Register a new user with email and password
tags:
- auth
x-auth:
- publishable_key
/api/v1/auth/register/link:
post:
description: 'Starts a passwordless registration flow by sending a verification link to the given
email address. The recipient clicks the link and is redirected to `redirect_uri` with
a token; pass that token to `/auth/verify_link` to complete registration and obtain
session tokens.
Profile fields (`full_name`, `alias`, `timezone`) are captured now and applied when
the link is verified. Requests are rate-limited per IP (10 per minute) and per
email-IP pair (3 per minute) — exceeding either limit returns HTTP 429. Returns
HTTP 204 on success.'
operationId: post_api_v1_auth_register_link
parameters: []
requestBody:
content:
application/json:
schema:
example:
alias: string
email: user@example.com
full_name: Example Name
redirect_uri: https://example.com
timezone: America/New_York
properties:
alias:
description: Display alias (handle) for the new account.
example: string
type: string
email:
description: Email address to send the registration magic link to.
example: user@example.com
type: string
full_name:
description: Full name for the new account.
example: Example Name
type: string
redirect_uri:
description: URL the user is redirected to after clicking the registration link. The token is appended as a query parameter.
example: https://example.com
type: string
timezone:
description: IANA timezone name for the new account, e.g. `"America/New_York"`.
example: America/New_York
type: string
type: object
required: true
responses:
'204':
description: No content
'400':
description: Missing email
'422':
description: Validation failed
'429':
description: Rate limited
summary: Request a magic link for registration
tags:
- auth
x-auth:
- publishable_key
x-sdk-name: request_register_magic_link
/api/v1/auth/request/link:
post:
description: 'Sends a passwordless magic link to the given email address. If an account with that
email already exists, a login link is sent. If no account exists, a registration link
is sent and the recipient completes sign-up by clicking through. This unified endpoint
lets you implement a single email-entry UI that handles both cases transparently.
The `redirect_uri` is validated against the app''s registered hosts; an unregistered
URI returns HTTP 400. Both `email` and `redirect_uri` are required. Requests are
rate-limited per IP (10 per minute) and per email-IP pair (3 per minute). Returns
HTTP 204 on success — no body.'
operationId: post_api_v1_auth_request_link
parameters: []
requestBody:
content:
application/json:
schema:
example:
email: user@example.com
redirect_uri: https://example.com
properties:
email:
description: Email address to send the magic link to.
example: user@example.com
type: string
redirect_uri:
description: URL the user is redirected to after clicking the magic link. Must be registered with the app.
example: https://example.com
type: string
type: object
required: true
responses:
'204':
description: No content
'400':
description: Missing email or redirect_uri
'422':
description: Validation failed
'429':
description: Rate limited
summary: Request a magic link for login or registration
tags:
- auth
x-auth:
- publishable_key
x-sdk-name: request_magic_link
/api/v1/auth/token:
post:
description: 'Consumes a single-use login token delivered via email and returns an access token,
refresh token, and the authenticated user object. One-time tokens are issued by the
passwordless login flow and expire after a short window; submitting an expired or
already-used token returns HTTP 401.
If `timezone` is provided and the user''s current timezone is still the default
(`"America/Los_Angeles"`), the account timezone is updated in the same request.
Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.'
operationId: post_api_v1_auth_token
parameters: []
requestBody:
content:
application/json:
schema:
example:
timezone: America/New_York
token: string
properties:
timezone:
description: IANA timezone name to apply to the account if the account timezone is still the default, e.g. `"Europe/London"`. Omit to leave the timezone unchanged.
example: America/New_York
type: string
token:
description: Single-use login token extracted from the magic link or email code flow.
example: string
type: string
required:
- token
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokens'
description: Successful response
'400':
description: Missing token
'401':
description: Invalid or expired token
'429':
description: Rate limited
'500':
description: Token exchange failed
summary: Exchange a one-time login token for session tokens
tags:
- auth
x-auth:
- publishable_key
x-sdk-name: exchange_login_token
/api/v1/auth/verify/link:
post:
description: 'Consumes a single-use token from a magic link URL and returns an access token,
refresh token, and the authenticated user object. This endpoint completes both the
login flow (initiated by `/auth/request_login_link`) and the registration flow
(initiated by `/auth/request_register_link` or `/auth/request_link`).
Extract the token from the `token` query parameter of the magic link redirect URI
and POST it here. Expired or already-used tokens return HTTP 401. If the app has
disabled passwordless authentication the request returns HTTP 403. Rate-limited to
10 requests per IP per minute — exceeding this returns HTTP 429.'
operationId: post_api_v1_auth_verify_link
parameters: []
requestBody:
content:
application/json:
schema:
example:
token: string
properties:
token:
description: Single-use magic link token extracted from the redirect URI query parameter.
example: string
type: string
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthTokens'
description: Successful response
'400':
description: Missing token
'401':
description: Invalid or expired token
'403':
description: Passwordless login is not enabled for this organization
'429':
description: Rate limited
summary: Verify a magic link token
tags:
- auth
x-auth:
- publishable_key
x-sdk-name: verify_magic_link
components:
schemas:
User:
description: A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.
example:
alias: jdoe
app: dap_0aBcDeFgHiJkLmNoPqRsTu
app_name: Example Name
email: user@example.com
id: usr_0aBcDeFgHiJkLmNoPqRsTu
is_system_user: true
metadata:
key: value
name: Example Name
org: org_0aBcDeFgHiJkLmNoPqRsTu
org_name: Example Name
org_role: member
sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
sandbox_name: Example Name
properties:
alias:
description: Short handle or alias for the user. `null` if not set.
example: jdoe
type: string
app:
description: ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.
example: dap_0aBcDeFgHiJkLmNoPqRsTu
type: string
app_name:
description: Display name of the user's app. `null` when the app association was not preloaded by the caller.
example: Example Name
type: string
email:
description: Email address of the user.
example: user@example.com
type: string
id:
description: User ID (`usr_...`).
example: usr_0aBcDeFgHiJkLmNoPqRsTu
type: string
is_system_user:
description: '`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.'
example: true
type: boolean
metadata:
description: Arbitrary key-value metadata attached to the user. Defaults to an empty object.
example:
key: value
type: object
name:
description: Full display name of the user. `null` if the user has not set a name.
example: Example Name
type: string
org:
description: ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.
example: org_0aBcDeFgHiJkLmNoPqRsTu
type: string
org_name:
description: Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.
example: Example Name
type: string
org_role:
description: Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.
example: member
type: string
sandbox:
description: ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.
example: dsb_0aBcDeFgHiJkLmNoPqRsTu
type: string
sandbox_name:
description: Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.
example: Example Name
type: string
required:
- id
type: object
AuthTokens:
description: Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user.
example:
expires_in: 3600
metadata:
key: value
refresh_token: rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
token_type: Bearer
user:
alias: jdoe
app: dap_0aBcDeFgHiJkLmNoPqRsTu
app_name: Example Name
email: user@example.com
id: usr_0aBcDeFgHiJkLmNoPqRsTu
is_system_user: true
metadata:
key: value
name: Example Name
org: org_0aBcDeFgHiJkLmNoPqRsTu
org_name: Example Name
org_role: member
sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
sandbox_name: Example Name
properties:
expires_in:
description: Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token.
example: 3600
type: integer
x-sdk: token_expiry
metadata:
description: Optional auxiliary data associated with this authentication event, such as `onboarding_job_id` when the user is completing onboarding. `null` when no extra context is present.
example:
key: value
type: object
refresh_token:
description: Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires.
example: rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
type: string
x-sdk: refresh_token
token:
description: 'Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests.'
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
type: string
x-sdk: access_token
token_type:
description: Token scheme. Always `"Bearer"`.
example: Bearer
type: string
user:
$ref: '#/components/schemas/User'
description: The user who authenticated. Contains the user's profile and account details.
required:
- expires_in
- refresh_token
- token
- token_type
- user
type: object
x-archastro-docs-scope: external
x-auth-schemes:
bearer:
description: User JWT in Authorization header
scheme: bearer
type: http
device_flow:
description: Third-party device flow token — requires per-action opt-in
scheme: bearer
type: http
x-token-use: third_party
publishable_key:
description: Publishable API key — identifies the app
in: header
name: x-archastro-api-key
prefix: pk_
type: api_key
secret_key:
description: Secret API key — full admin access, no user JWT required
in: header
name: x-archastro-api-key
prefix: sk_
type: api_key
x-channel-auth:
- bearer
x-channels:
- description: 'Channel for real-time chat messaging.
Supports team-scoped and user-scoped threads with keyed, transient, and direct
thread access patterns.'
joins:
- description: Join a team-scoped thread by ID
name: join_team_thread
params:
example:
after_cursor: string
before_cursor: string
include_metadata: true
limit: 1
team_id: string
thread_id: string
properties:
after_cursor:
example: string
type: string
before_cursor:
example: string
type: string
include_metadata:
example: true
type: boolean
limit:
example: 1
type: integer
team_id:
example: string
type: string
thread_id:
example: string
type: string
required:
- team_id
- thread_id
type: object
pattern: api:chat:team:{team_id}:thread:{thread_id}
returns:
type: object
- description: Join a team-scoped transient (ephemeral) thread
name: join_team_transient
params:
example:
after_cursor: string
before_cursor: string
include_metadata: true
key: string
limit: 1
team_id: string
properties:
after_cursor:
example: string
type: string
before_cursor:
example: string
type: string
include_metadata:
example: true
type: boolean
key:
example: string
type: string
limit:
example: 1
type: integer
team_id:
example: string
type: string
required:
- key
- team_id
type: object
pattern: api:chat:team:{team_id}:transient:{key}
returns:
type: object
- description: Join a user-scoped thread by ID
name: join_user_thread
params:
example:
after_cursor: string
before_cursor: string
include_metadata: true
limit: 1
thread_id: string
properties:
after_cursor:
example: string
type: string
before_cursor:
example: string
type: string
include_metadata:
example: true
type: boolean
limit:
example: 1
type: integer
thread_id:
example: string
type: string
required:
- thread_id
type: object
pattern: api:chat:user:thread:{thread_id}
returns:
type: object
- description: Join a user-scoped transient (ephemeral) thread
name: join_user_transient
params:
example:
after_cursor: string
before_cursor: string
include_metadata: true
key: string
limit: 1
properties:
after_cursor:
example: string
type: string
before_cursor:
example: string
type: string
include_metadata:
example: true
type: boolean
key:
example: string
type: string
limit:
example: 1
type: integer
required:
- key
type: object
pattern: api:chat:user:transient:{key}
returns:
type: object
- description: Join or create a team-scoped keyed thread
name: join_team_keyed
params:
example:
after_cursor: string
before_cursor: string
include_metadata: true
key: string
limit: 1
team_id: string
properties:
after_cursor:
example: string
type: string
before_cursor:
example: string
type: string
include_metadata:
example: true
type: boolean
key:
example: string
type: string
limit:
example: 1
type: integer
team_id:
example: string
type: string
required:
- key
- team_id
type: object
pattern: api:chat:team:{team_id}:key:{key}
returns:
type: object
- description: Join or create a user-scoped keyed thread
name: join_user_keyed
params:
example:
after_cursor: string
before_cursor: string
include_metadata: true
key: string
limit: 1
properties:
after_cursor:
example: string
type: string
before_cursor:
example: string
type: string
include_metadata:
example: true
type: boolean
key:
example: string
type: string
limit:
example: 1
type: integer
required:
- key
type: object
pattern: api:chat:user:key:{key}
returns:
type: object
messages:
- description: Add an emoji reaction to a message
event: api:chat:add_reaction
params:
example:
emoji: string
message_id: string
properties:
emoji:
example: string
type: string
message_id:
example: string
type: string
required:
- emoji
- message_id
type: object
returns:
description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
properties: {}
type: object
- description: Delete a message
event: api:chat:delete_message
params:
example:
message_id: string
properties:
message_id:
example: string
type: string
required:
- message_id
type: object
returns:
description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
properties: {}
type: object
- description: Edit an existing message's content
event: api:chat:edit_message
params:
example:
content: string
message_id: string
# --- truncated at 32 KB (1008 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-auth-api-openapi.yml