v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Join a team with an invite 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.

post/api/v1/teams/join_by_code

Request body

agentstring

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_codestring

12-character invite code — alias for join_code accepted for backwards compatibility.

join_codestring

12-character invite code that identifies the team. Mutually usable with invite_code.

userstring

User ID (user_...) to add to the team. Required for server-to-server requests when agent is not supplied.

Example request

{
  "agent": "string",
  "invite_code": "string",
  "join_code": "string",
  "user": "string"
}

Response

Successful response

appstring

ID of the developer application this team belongs to (dap_...). null if the team is not scoped to an app.

badgesobject

Aggregated badge counts for the team, keyed by category. null when badge data is not loaded.

created_atstring date-time

When this team was created (ISO 8601).

descriptionstring

Human-readable description of the team's purpose. null if not set.

idstring required

Team ID (tem_...).

membership_statusstring

The authenticated viewer's role on this team. One of "owner", "admin", or "member". null if the viewer is not a member.

metadataobject

Arbitrary key-value metadata attached to this team. Returns an empty object when no metadata has been set.

namestring

Display name of the team.

orgstring

ID of the organization this team belongs to (org_...). null if the team is not org-scoped.

sandboxstring

ID of the developer sandbox this team is scoped to (dsb_...). null outside sandbox contexts.

slugstring

URL-safe slug for the team, derived from the team name. null if not set.

updated_atstring date-time

When this team was last updated (ISO 8601).

Example response

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "badges": {},
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "id": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "membership_status": "member",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "slug": "example-slug",
  "updated_at": "2024-01-01T00:00:00Z"
}