docs
API

Invites

Invites are pending membership requests sent to an email address. When an invite is accepted through the Phase console, the recipient becomes an organisation member with the assigned role. On this page, we'll look at the API endpoints for creating, listing, and cancelling pending invites.

Invites live under the Members resource — all endpoints are namespaced as /v1/members/invites/. The POST /v1/members/ endpoint is reserved for the future direct-member-creation flow and currently returns 405 Method Not Allowed.

The Invite model

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the invite.

  • Name
    inviteeEmail
    Type
    string
    Description

    The email address the invite was sent to.

  • Name
    role
    Type
    object
    Description

    The role that will be assigned on acceptance, with id and name.

  • Name
    invitedBy
    Type
    object
    Description

    Who sent the invite. Contains type ("member" or "service_account") and either email (for members) or name (for service accounts). null if the sender has since been removed.

  • Name
    createdAt
    Type
    timestamp
    Description

    Timestamp of when the invite was created.

  • Name
    expiresAt
    Type
    timestamp
    Description

    Timestamp of when the invite expires. Invites are valid for 14 days.

  • Name
    valid
    Type
    boolean
    Description

    Whether the invite is still valid (has not been cancelled or accepted).

POST/v1/members/invites

Create Invite

Send an invitation to a new member. An invite email is sent to the specified address, and the invite expires after 14 days.

This endpoint creates an invite, not a direct membership. The invited user must accept the invite via the console to become a member.

Constraints

  • The role must not have global access (i.e. Owner and Admin roles cannot be invited to).
  • The role must not permit creating service account tokens.
  • The email is validated against RFC format; whitespace is trimmed and the local + domain parts are lowercased. Invalid emails return 400 Bad Request.
  • The email must not already belong to an active member or a pending invite. Duplicate invites return 409 Conflict with {"error": "An active invite already exists for '<email>'."}.

App and environment access cannot be scoped at invite time. Because Phase is end-to-end encrypted, granting access requires the invitee's identity key, which doesn't exist until they accept the invite and complete their key ceremony. Use Manage Access after acceptance. Sending an apps field returns 400 Bad Request.

JSON Body

Required fields

  • Name
    email
    Type
    string
    Description

    The email address of the person to invite.

  • Name
    role_id
    Type
    string
    Description

    The ID of the role to assign on acceptance.

Request

POST
/v1/members/invites
curl -X POST https://api.phase.dev/v1/members/invites/ \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role_id": "6aec9df5-cd75-4645-a9d0-8b6f6aff78d6"
  }'

Response

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "inviteeEmail": "[email protected]",
    "role": {
        "id": "6aec9df5-cd75-4645-a9d0-8b6f6aff78d6",
        "name": "Developer"
    },
    "invitedBy": {
        "type": "member",
        "email": "[email protected]"
    },
    "createdAt": "2024-06-02T10:00:00Z",
    "expiresAt": "2024-06-16T10:00:00Z",
    "valid": true
}
GET/v1/members/invites

List Invites

Retrieve all pending (valid, non-expired) invites for the organisation, ordered by most recent first.

Request

GET
/v1/members/invites
curl https://api.phase.dev/v1/members/invites/ \
  -H "Authorization: Bearer {token}"

Response

{
    "data": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "inviteeEmail": "[email protected]",
            "role": {
                "id": "6aec9df5-cd75-4645-a9d0-8b6f6aff78d6",
                "name": "Developer"
            },
            "invitedBy": {
                "type": "member",
                "email": "[email protected]"
            },
            "createdAt": "2024-06-02T10:00:00Z",
            "expiresAt": "2024-06-16T10:00:00Z",
            "valid": true
        },
        {
            "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "inviteeEmail": "[email protected]",
            "role": {
                "id": "d3a2124c-9770-42d5-abf8-599b4a372e9d",
                "name": "Manager"
            },
            "invitedBy": {
                "type": "service_account",
                "name": "deploy-bot"
            },
            "createdAt": "2024-06-01T08:00:00Z",
            "expiresAt": "2024-06-15T08:00:00Z",
            "valid": true
        }
    ]
}
DELETE/v1/members/invites/:id

Cancel Invite

Cancel a pending invite. The invite is immediately invalidated and the invitee can no longer use the invite link to join the organisation.

URL parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the invite.

Request

DELETE
/v1/members/invites/:id
curl -X DELETE https://api.phase.dev/v1/members/invites/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  -H "Authorization: Bearer {token}"

Response

204 No Content