MessageBird User Management API Guide

Auth method: API Key (Bearer token via Authorization header)

Setup steps

1. Log in to the MessageBird (Bird) Dashboard at https://dashboard.messagebird.com.
2. Navigate to Developers > API access.
3. Create a new API key with the required permissions (live or test mode).
4. Include the key in all requests as: Authorization: AccessKey

Required scopes

List users in organization

• Method: GET
• URL: https://rest.messagebird.com/users
• Watch out for: Endpoint availability may require organization-level API key, not a personal key.

Request example

GET /users?limit=20&offset=0
Authorization: AccessKey <api_key>

Response example

{
  "offset": 0,
  "limit": 20,
  "count": 2,
  "items": [
    {"id": "uuid", "email": "user@example.com", "role": "admin"}
  ]
}

Get single user

• Method: GET
• URL: https://rest.messagebird.com/users/{userId}
• Watch out for: Returns 404 if userId does not exist in the calling organization.

Request example

GET /users/abc-123
Authorization: AccessKey <api_key>

Response example

{
  "id": "abc-123",
  "email": "user@example.com",
  "firstName": "Jane",
  "role": "member",
  "status": "active"
}

Invite/create user

• Method: POST
• URL: https://rest.messagebird.com/users
• Watch out for: User receives an email invitation; account is not active until invitation is accepted.

Request example

POST /users
Authorization: AccessKey <api_key>
Content-Type: application/json

{"email": "new@example.com", "role": "member"}

Response example

{
  "id": "new-uuid",
  "email": "new@example.com",
  "status": "invited"
}

Update user

• Method: PATCH
• URL: https://rest.messagebird.com/users/{userId}
• Watch out for: Only fields included in the request body are updated; omitted fields are unchanged.

Request example

PATCH /users/abc-123
Authorization: AccessKey <api_key>
Content-Type: application/json

{"role": "admin"}

Response example

{
  "id": "abc-123",
  "role": "admin",
  "updatedAt": "2024-06-01T10:00:00Z"
}

Delete/remove user

• Method: DELETE
• URL: https://rest.messagebird.com/users/{userId}
• Watch out for: Deletion is immediate and irreversible; user loses all access to the organization.

Request example

DELETE /users/abc-123
Authorization: AccessKey <api_key>

Response example

HTTP 204 No Content

SCIM: List users

• Method: GET
• URL: https://rest.messagebird.com/scim/v2/Users
• Watch out for: Requires Enterprise plan and a dedicated SCIM bearer token, not a standard API key.

Request example

GET /scim/v2/Users?startIndex=1&count=20
Authorization: Bearer <scim_token>

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 5,
  "Resources": [{"id": "uuid", "userName": "user@example.com"}]
}

SCIM: Create user

• Method: POST
• URL: https://rest.messagebird.com/scim/v2/Users
• Watch out for: SCIM provisioning is only available on Enterprise plans; requests on lower tiers return 403.

Request example

POST /scim/v2/Users
Authorization: Bearer <scim_token>
Content-Type: application/scim+json

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"userName":"user@example.com"}

Response example

{
  "id": "new-uuid",
  "userName": "user@example.com",
  "active": true
}

SCIM: Deactivate user

• Method: PATCH
• URL: https://rest.messagebird.com/scim/v2/Users/{userId}
• Watch out for: Setting active=false suspends the user but does not delete them; use DELETE to fully remove.

Request example

PATCH /scim/v2/Users/abc-123
Authorization: Bearer <scim_token>
Content-Type: application/scim+json

{"Operations":[{"op":"replace","path":"active","value":false}]}

Response example

{
  "id": "abc-123",
  "active": false
}

• Rate limits: MessageBird enforces per-second and per-day rate limits on REST API calls. Exact limits vary by endpoint and plan tier.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: Official per-plan rate limit figures are not publicly documented in detail. HTTP 429 is returned when limits are exceeded. Check response headers for limit context.
• Pagination method: offset
• Default page size: 20
• Max page size: 100
• Pagination pointer: offset / limit

• Webhooks available: No
• Webhook notes: MessageBird does not publicly document user-management-specific webhooks (e.g., user created, user deleted events). Webhooks are available for messaging events (inbound SMS, call flows, etc.) but not for IAM/user lifecycle events.
• Alternative event strategy: Poll the /users endpoint or use SCIM provisioning events via your IdP (e.g., Okta) for user lifecycle automation.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://rest.messagebird.com/scim/v2

• Supported operations: GET /Users, POST /Users, GET /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• Only available on Enterprise plan.
• Requires a dedicated SCIM bearer token generated from the dashboard, separate from standard API keys.
• Officially documented IdP integration is Okta; Entra ID (Azure AD) and Google Workspace are not confirmed.
• Full SCIM schema support (custom attributes, enterprise extensions) not publicly confirmed.
• MessageBird rebranded to Bird in 2024; documentation URLs and branding may differ.

Provisioning via SCIM from Okta is the documented path for Enterprise customers: generate a SCIM bearer token in Settings > SCIM, configure the base URL and token in the Okta app, then assign users - Okta sends POST /scim/v2/Users and Bird returns HTTP 201 with active: true. If the email already exists in Bird, expect HTTP 409; deduplicate or link the existing account before provisioning.

Deprovision flows split by plan tier. On Enterprise via SCIM, removing the user from the Okta app triggers PATCH /scim/v2/Users/{id} with active=false (suspends, retains record) followed optionally by DELETE (permanent removal). On any plan via REST, DELETE /users/{userId} with an org-level key removes access immediately and irreversibly - there is no soft-delete or recovery path, so choose based on your audit and compliance requirements.

For bulk audits, paginate GET /users?limit=100&offset=0, check the count field, and iterate by incrementing offset in steps of 100. Record id, email, role, and status per user. Note that offset pagination has no consistency guarantee during concurrent modifications - users added or removed mid-scan may appear duplicated or be skipped entirely.

Provision a new employee via SCIM from Okta

1. Ensure the organization is on an Enterprise plan.
2. In the MessageBird/Bird dashboard, navigate to Settings > SCIM and generate a SCIM bearer token.
3. In Okta, add the MessageBird SCIM app and configure the base URL (https://rest.messagebird.com/scim/v2) and bearer token.
4. Assign the Okta user to the MessageBird app; Okta sends POST /scim/v2/Users with the user's profile.
5. MessageBird creates the user and returns HTTP 201 with the new user's id and active: true.

Watch out for: If the user's email already exists in MessageBird, the SCIM POST may return a conflict error (HTTP 409). Resolve by linking the existing account or deduplicating before provisioning.

Deprovision a departing employee

1. Via SCIM (Enterprise): Remove the user from the MessageBird app in Okta; Okta sends PATCH /scim/v2/Users/{id} with active=false, then optionally DELETE /scim/v2/Users/{id}.
2. Via REST API (any plan): Call DELETE /users/{userId} with an organization-level API key.
3. Confirm the user no longer appears in GET /users or GET /scim/v2/Users.

Watch out for: PATCH active=false suspends access but retains the user record. DELETE permanently removes the user. Choose based on audit/compliance requirements.

Bulk-list and audit all organization users

1. Call GET /users?limit=100&offset=0 with an organization-level API key.
2. Check the count field in the response to determine total users.
3. Iterate with increasing offset values (0, 100, 200, ...) until all users are retrieved.
4. For each user, record id, email, role, and status for the audit report.

Watch out for: Max page size is 100. There is no cursor-based pagination, so concurrent modifications during iteration may cause users to be missed or duplicated across pages.

The most significant integration trap is the dual-token requirement: the REST API key and the SCIM bearer token are separate credentials with separate generation flows. Pipelines that conflate them will receive silent auth failures or 403s on SCIM endpoints without a clear error distinguishing the cause.

SCIM is hard-gated at Enterprise; POST /scim/v2/Users on a lower-tier plan returns HTTP 403 with no graceful degradation. Any integration that assumes SCIM availability without plan-checking will fail silently in non-Enterprise environments.

Additionally, POST /users via REST creates a user in 'invited' status - not 'active' - meaning downstream systems polling for active users immediately after provisioning will not find the new record until the invitation is accepted.

The 2024 rebrand from MessageBird to Bird means documentation URLs, dashboard paths, and some API references use inconsistent branding. Validate all endpoint URLs and dashboard navigation paths against current Bird documentation rather than cached MessageBird developer docs, as discrepancies exist.

Officially documented IdP integration is Okta only; Entra ID and Google Workspace SCIM compatibility are not confirmed in official documentation as of the research date.