Railway User Management API Guide

Auth method: Bearer token (Railway API token)

Setup steps

1. Log in to Railway dashboard at railway.app.
2. Navigate to Account Settings → API Tokens.
3. Click 'Create Token', give it a name, and copy the generated token.
4. Include the token in all API requests as an HTTP header: Authorization: Bearer .

Required scopes

Get current authenticated user

• Method: POST
• URL: https://backboard.railway.app/graphql/v2
• Watch out for: Returns the user associated with the API token used; cannot query arbitrary users.

Request example

{
  "query": "query { me { id name email avatar createdAt } }"
}

Response example

{
  "data": {
    "me": {
      "id": "usr_abc123",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "avatar": "https://...",
      "createdAt": "2023-01-15T10:00:00Z"
    }
  }
}

List team members

• Method: POST
• URL: https://backboard.railway.app/graphql/v2
• Watch out for: Requires the API token owner to be a member of the queried team.

Request example

{
  "query": "query { team(id: \"team_xyz\") { members { edges { node { id name email role } } } } }"
}

Response example

{
  "data": {
    "team": {
      "members": {
        "edges": [
          { "node": { "id": "usr_abc", "name": "Jane", "email": "jane@example.com", "role": "ADMIN" } }
        ]
      }
    }
  }
}

Invite user to team

• Method: POST
• URL: https://backboard.railway.app/graphql/v2
• Watch out for: Sends an email invitation; user must accept before appearing as an active member. Requires ADMIN role in the team.

Request example

{
  "query": "mutation { teamInviteUser(teamId: \"team_xyz\", email: \"new@example.com\", role: MEMBER) { id } }"
}

Response example

{
  "data": {
    "teamInviteUser": {
      "id": "invite_001"
    }
  }
}

Remove user from team

• Method: POST
• URL: https://backboard.railway.app/graphql/v2
• Watch out for: Cannot remove the last ADMIN from a team. Requires ADMIN role.

Request example

{
  "query": "mutation { teamRemoveMember(teamId: \"team_xyz\", userId: \"usr_abc\") }"
}

Response example

{
  "data": {
    "teamRemoveMember": true
  }
}

Update team member role

• Method: POST
• URL: https://backboard.railway.app/graphql/v2
• Watch out for: Only ADMIN team members can update roles.

Request example

{
  "query": "mutation { teamMemberUpdate(teamId: \"team_xyz\", userId: \"usr_abc\", role: ADMIN) { id role } }"
}

Response example

{
  "data": {
    "teamMemberUpdate": {
      "id": "usr_abc",
      "role": "ADMIN"
    }
  }
}

List teams for current user

• Method: POST
• URL: https://backboard.railway.app/graphql/v2
• Watch out for: Only returns teams the token owner belongs to.

Request example

{
  "query": "query { me { teams { edges { node { id name } } } } }"
}

Response example

{
  "data": {
    "me": {
      "teams": {
        "edges": [
          { "node": { "id": "team_xyz", "name": "Acme Corp" } }
        ]
      }
    }
  }
}

• Rate limits: Railway does not publicly document specific rate limit thresholds or headers in its official API docs as of the policy date.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No official rate limit documentation found. Excessive requests may result in temporary throttling without documented limits.

• Pagination method: cursor

• Default page size: 0

• Max page size: 0

• Pagination pointer: after

• Webhooks available: No

• Webhook notes: Railway does not offer user-management or team-membership webhooks as of the policy date. Deployment and service event webhooks exist but are not user-management events.

• Alternative event strategy: Poll the GraphQL API (e.g., team members query) to detect membership changes.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• No native SCIM 2.0 support documented by Railway as of the policy date.
• Enterprise plan is required for SSO; SCIM provisioning is not listed as an Enterprise feature in official docs.
• No IdP-specific SCIM connector documented for Okta, Entra ID, or Google Workspace.

Three core identity graph operations are supported via the API.

To onboard a member, call the teamInviteUser mutation with the target email and role; the invitation is asynchronous and email-based, so the user does not appear in team { members } queries until they accept - do not treat a successful mutation response as confirmation of active access.

To audit membership, query team(id: "<teamId>") { members { edges { node { id name email role } } } } and paginate with the cursor after parameter; note that pending (unaccepted) invitations are not documented as appearing in this result set, creating a gap in identity graph completeness.

To remove a departed user, resolve their userId by matching on email in the members query, then call teamRemoveMember with the teamId and userId; confirm removal with a follow-up members query.

A critical caveat: Railway exposes no admin API to revoke another user's API tokens - any tokens the removed user created remain valid until the user revokes them or Railway support intervenes at the account level.

Onboard a new team member

1. Authenticate with a Bearer token belonging to a team ADMIN.
2. Call teamInviteUser mutation with the new member's email and desired role (MEMBER or ADMIN).
3. New user receives an email invitation and must accept it via the Railway dashboard.
4. After acceptance, verify membership by querying team { members } and confirming the user appears.

Watch out for: The user is not active until they accept the invitation; do not assume immediate access after the mutation succeeds.

Audit current team membership

1. Authenticate with a Bearer token belonging to a team member.
2. Query team(id: "") { members { edges { node { id name email role } } } }.
3. Paginate using the cursor-based 'after' parameter if the team has many members.
4. Compare returned members against your identity provider or HR system records.

Watch out for: Pending (unaccepted) invitations may not appear in the members list; there is no documented query for pending invites.

Remove a departed employee from a team

1. Resolve the user's Railway userId by querying team members and matching on email.
2. Call teamRemoveMember mutation with the teamId and resolved userId.
3. Confirm removal by re-querying team members and verifying the user is absent.
4. Revoke any Railway API tokens the user may have created (must be done by the user or via account deletion - no admin token-revocation API is documented).

Watch out for: Railway does not expose an admin API to revoke another user's API tokens. Coordinate with the user or escalate to Railway Enterprise support for account-level actions.

The Railway API covers the happy path for team membership CRUD but has several gaps that matter for automated identity lifecycle management. Token-level permissions are all-or-nothing and tied to a human account, which means any automation pipeline breaks if the token owner loses their Admin role or leaves the team.

There is no SCIM 2.0 endpoint at any pricing tier, and no IdP connector is documented for Okta, Entra ID, or Google Workspace - SSO itself is Enterprise-only and does not include provisioning. Webhooks for user-management events do not exist; detecting membership drift requires polling.

Combined, these constraints mean that building a reliable, automated identity graph sync against Railway requires defensive polling, manual token lifecycle management, and out-of-band coordination for account-level actions.