---
title: "Join a team with an invite code"
method: POST
path: "/api/v1/teams/join_by_code"
---

# Join a team with an invite code

`POST /api/v1/teams/join_by_code`

Adds a principal to a team using a 12-character invite code. The invite
code can be supplied as either `join_code` or `invite_code`; both are
accepted for backwards compatibility.

For user-authenticated requests, the currently authenticated user is added
to the team. For server-to-server requests, you must supply either `agent`
(to add an agent) or `user` (to add a specific user by ID). If the user
is already a member of the team, the request succeeds without creating a
duplicate membership.

This endpoint is rate-limited to 10 requests per minute per IP address to
prevent invite-code enumeration.

## Request body

- object
  - `agent` string — Agent ID (`agent_...`) to add to the team. When provided, the agent is joined instead of the authenticated user. Requires a server-to-server session.
  - `invite_code` string — 12-character invite code — alias for `join_code` accepted for backwards compatibility.
  - `join_code` string — 12-character invite code that identifies the team. Mutually usable with `invite_code`.
  - `user` string — User ID (`user_...`) to add to the team. Required for server-to-server requests when `agent` is not supplied.

## Response `200`

Successful response

- Team — A team within an organization, used to group users and agents and scope resources like configs, agents, and tasks.
  - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
    - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
      - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
  - `app` string — ID of the developer application this team belongs to (`dap_...`). `null` if the team is not scoped to an app.
  - `badges` object — Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.
  - `created_at` string, date-time — When this team was created (ISO 8601).
  - `description` string — Human-readable description of the team's purpose. `null` if not set.
  - `id` string, required — Team ID (`tem_...`).
  - `membership_status` string — The authenticated viewer's role on this team. One of `"owner"`, `"admin"`, or `"member"`. `null` if the viewer is not a member.
  - `metadata` object — Arbitrary key-value metadata attached to this team. Returns an empty object when no metadata has been set.
  - `name` string — Display name of the team.
  - `org` string — ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.
  - `sandbox` string — ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.
  - `slug` string — URL-safe slug for the team, derived from the team name. `null` if not set.
  - `updated_at` string, date-time — When this team was last updated (ISO 8601).

## Other responses

- `400` — Invalid join code format
- `401` — Unauthorized
- `404` — Invalid or expired join code
- `429` — Too many requests

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)