---
title: "Provision an app user"
method: POST
path: "/api/apps/{app_id}/users/provisions"
---

# Provision an app user

`POST /api/apps/{app_id}/users/provisions`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/apps/{app_id}/users/provisions`
- Auth: one of:
  - HTTP bearer
  - API key in header `api_key`
  - HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Gives a person access to this app ahead of their first sign-in, so the app can be embedded signed in as them. Returns `created` for a new email, and `exists` for an email that already has an access request, whatever its state: a request still pending approval stays pending, and an embed sign-in token for it answers `unknown_user`. Call it with a personal access token whose owner can edit the app, or with a workspace API key that has the **Provision app users** permission. Limited to 120 requests a minute per app, shared with deprovisioning. Higher plans get a higher limit.

## Path parameters

- `app_id` string, required: ID of the app.

## Request body

- ProvisionUserPayload: Payload for server-to-server app-user provisioning (embedded platforms).
  - `email` string, email, required: The app user's email — their identity in this app
  - `role` string, required: Application-level role for in-app permissions
  - `full_name` string, nullable

## Response `200`

Successful Response

- ProvisionUserResponse: The app user an email was provisioned as.
  - `status` 'created' | 'exists', required: `created` for a new email, `exists` for one that already had an access request.
  - `email` string, required: The email, lowercased.
  - `role` string, required: The role the email holds in the app. For `exists`, the role it already had.

## Other responses

- `400`: `role` is not one of the app's roles: error.code invalid_role.
- `401`: Missing or invalid credentials.
- `403`: The key can't provision users of this app.
- `404`: App not found.
- `422`: Validation Error
- `429`: The app went over its per-minute limit for provision and deprovision requests combined.

## Changes

- **2026-10-20** `bbcd7d7e2e72`: 1 info
  - the endpoint scheme security `WorkspaceApiKeyBearerAuth` was added to the API
- **2026-10-11** `80287813ab84`: 2 info
  - the security scope `app_users:provision` was added to the endpoint's security scheme `WorkspaceApiKeyAuth`
  - the security scope `full_access` was added to the endpoint's security scheme `PersonalAccessTokenAuth`
- **2026-10-01** `e58d4ff7b1f8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/base44/apis/base44-app-management-api/changes/api/apps/:app_id/users/provisions/post.md)

---

[API](https://skmtc.dev/base44/apis/base44-app-management-api.md) - [All operations](https://skmtc.dev/base44/apis/base44-app-management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/base44/apis/base44-app-management-api/revisions/c534f09cf314?raw)