# User Export API The User Export API allows developers to bulk export users into a [CSV](https://datatracker.ietf.org/doc/html/rfc4180) or [ndjson](https://github.com/ndjson/ndjson-spec) file. The export process is asynchronous. That is, the process runs in the background. Hence, you will need to initiate an export task in one endpoint call and then, make an additional call to another endpoint to get the status of the export task. ### Authentication To use the Export User API, your application must be authenticated using an [Admin API JWT token](https://docs.authgear.com/reference/apis/admin-api/authentication-and-security). Once you obtain a valid Admin API JWT, you can set it as a Bearer Authorization header to access the Export User API Endpoints. The API will return a "403 Forbidden" error if an invalid JWT is used. ## Endpoints [![Run In Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/25586250-e38e5bf3-3b2e-4a6e-87d6-c5939e9dadd1?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D25586250-e38e5bf3-3b2e-4a6e-87d6-c5939e9dadd1%26entityType%3Dcollection%26workspaceId%3D0e6e6700-48e7-498b-a5ed-c9fd5cdd1cf2) The following are the two endpoints for the User Export API: ### Initiate Export Task `POST` `/_api/admin/users/export` Use this endpoint to create a new user export task. **Headers** | Name | Value | | ------------- | -------------------------------- | | Content-Type | `application/json` | | Authorization | `Bearer ` | | Host | `` | **Body** The Initiate Export endpoint accepts JSON input via an HTTP(S) request body. The following is an example of the input: ```json { "format": "csv", "csv": { "fields": [ { "pointer": "/sub", "field_name": "user_id" }, { "pointer": "/email" } ] } } ``` * The `format` field is where you specify the format of the export file. The value can be `csv` or `ndjson`. * `csv`: use this field when `format` is set to `csv`. The value is an object with a `fields` property. * `csv.fields`: you can use this field to list all the user attributes you want to include as fields in the CSV file. The value should be an array and each item in the array is an object with a `pointer` and an optional `field_name` property that describe a user attribute. #### **User Profile Attribute Pointers** The following is a complete list of supported pointers: | Pointer | Description | Value | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `/sub` | `sub` is short for "subject" and it is a standard field in O. The value is the user's unique ID generated by Authgear | String | | `/preferred_username` | the user's chosen username. | String | | `/email` | the email address associated with the current user account | String | | `/phone_number` | a phone number associated with the current user's account | String | | `/email_verified` | contains a boolean value that represents the current status of the user's email verification. The value can be either `true` or `false`. | Boolean | | `/phone_number_verified` | returns `true` if the associated phone number is verified and `false` if it's not. | Boolean | | `/name` | the user's display name. | String | | `/given_name` | the user's given name | String | | `/middle_name` | the user's middle name | String | | `/nickname` | a nickname set by the user. | String | | `/profile` | link to the user's profile | String | | `/picture` | contains the URL to the user's profile photo. | String | | `/website` | the user's website. That is, the value a user sets in the website attribute for their profile. | String | | `/gender` | holds the value set for the current users' gender (male, female, or some other string). | String | | `/birthdate` | the user's birthday set in their profile's standard attribute. | String | | `/zoneinfo` | the user's timezone. For example `Asia/Hong_Kong`, `Europe/London`. | String | | `/locale` | display language set by user. For example `en` for English. | String | | `/address/street_address` | the value the user sets for the street address field in their address standard attribute. | String | | `/address/locality` | the value the user sets for the city (locality) field in their address standard attribute. | String | | `/address/region` | the value the user sets for the "State / Province / Prefecture / Region" field in their address standard attribute. | String | | `/address/postal_code` | the postcode in the user's address standard attribute. | String | | `/address/country` | the value the user sets for the country field in their address standard attribute. | String | | `/roles` | a list of all the [roles](https://docs.authgear.com/~/changes/4UGStBVc3npNySIR4GYW/how-to-guide/user-management/manage-users-roles-and-groups) assigned to the current user. | Array | | `/groups` | a list of all the access management [groups](https://docs.authgear.com/~/changes/4UGStBVc3npNySIR4GYW/how-to-guide/user-management/manage-users-roles-and-groups) the user has been added to. | Array | | `/disabled` | the status of the user's account. The value is `false` if the account is not disabled and `true` if it is disabled. | Boolean | | `/identities` | a list of all the identities associated with a user's account. The structure of the value looks like this: `[{"claims":{"email":"user@gmail.com"},"login_id":{"key":"email","original_value":"user@gmail.com","type":"email","value":"user@gmail.com"},"type":"login_id"},{"claims":{"phone_number":"+447012341234"},"login_id":{"key":"phone","original_value":"+44712341234","type":"phone","value":"+447012341234"},"type":"login_id"}]` | Array | | `/mfa/emails` | a list of email addresses the user has added to receive 2FA login link or OTP. | Array | | `/mfa/phone_numbers` | a list of phone numbers the user has added to receive OTP via SMS or WhatsApp. | Array | | `/mfa/totps` | a list of JSON objects that contain details such as secret and uri for TOTP. The following an example of the struture of the data in this field: `[ { "secret":"ABCD1234EF...", "uri":"otpauth://totp/user@gmail.com?algorithm=SHA1\u0026digits=6\u0026issuer=https%3A%2F%2F127.0.0.1\u0026period=30\u0026secret=ABCD1234EF..." } ]` | Array | | `/biometric_count` | number of of biometric registered for the user. | Integer | | `/passkey_count` | number of passkey registered for the user. | Integer | If `csv.fields` is not specified, all the above pointers will be included as fields in the exported CSV file. The value for `pointer` for a custom attribute will follow this format: ```json {"pointer": "/custom_attributes/CUSTOM_ATTRIBUTE_NAME"} ``` For example, a custom attribute named `member_id` will be `{"pointer": "/custom_attributes/member_id"}`. If `field_name` is not given, then it is derived from `pointer` using the following rules: 1. Let `parts` be the list of the reference tokens in `pointer`. 2. Join `parts` with the character `.`. For example, following the above roles, the derived field\_name for `{"pointer": "/address/formatted"}` will be `address.formatted`. **Response** The body of an HTTP(S) request to the **Initiate Export** endpoint looks like this: {% tabs %} {% tab title="200" %} ```json { "result": { "id": "userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ", "created_at": "2024-10-07T21:06:24.361634372Z", "status": "pending", "request": { "format": "csv", "csv": { "fields": [ { "pointer": "/sub", "field_name": "user_id" }, { "pointer": "/email" }, { "pointer": "/mfa/emails" } ] } } } } ``` {% endtab %} {% tab title="403" %} ``` Forbidden ``` {% endtab %} {% endtabs %} * `id`: the value for this field is the export task ID required in the check status endpoint. * `created_at`: contains the date and time an export task was created. * `status`: returns `pending` when the task is created successfully. **Error Response** | Description | Name | Reason | Info | | ----------------------------------- | ---------------- | ----------------------------------- | -------------------------------------------------------------------------------------- | | When user export is disabled | `InternalError` | `UserExportDisabled` | - | | When the rate limit exceeded | `TooManyRequest` | `RateLimited` | {"bucket\_name": "UserExport"} | | When there is a running export | `TooManyRequest` | `MaximumConcurrentJobLimitExceeded` | - | | When the input fails the validation | `Invalid` | `ValidationFailed` | The info should contain the JSON schema validation output | | When the field names are not unique | `Invalid` | `UserExportNonUniqueFieldNames` | Output the full list of "field\_names". Like `{"field_names": ["sub", "a", "b", "a"]}` | ### Check Status `GET` `/_api/admin/users/export/{Task ID}` Use this endpoint to query the status of an existing export task. Replace `{Task ID}` with the task `id` returned in the response body of the initiate export endpoint. **Headers** | Name | Value | | ------------- | -------------------------------- | | Content-Type | `application/json` | | Authorization | `Bearer ` | | Host | `` | **Response** The following is what the response body of the **Check Status** endpoint looks like: {% tabs %} {% tab title="200" %} ```json { "result": { "id": "userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ", "created_at": "2024-10-07T21:06:24.361634372Z", "completed_at": "2024-10-07T21:06:24.551711713Z", "status": "completed", "request": { "format": "csv", "csv": { "fields": [ { "pointer": "/sub", "field_name": "user_id" }, { "pointer": "/email" }, { "pointer": "/mfa/emails" } ] } }, "download_url": "https://storage.googleapis.com/authgear-userexport-staging/example-userexport_userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ-20241007210624Z.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=authgear-server%40oursky-kube.iam.gserviceaccount.com%2F20241007%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20241007T210641Z&X-Goog-Expires=59&X-Goog-Signature=abcd12e45&X-Goog-SignedHeaders=host" } } ``` {% endtab %} {% tab title="403" %} ``` Forbidden ``` {% endtab %} {% endtabs %} * The `status` field reports progress on the current export task. If the value is `completed`, the export is complete, and you can now download the export file. * `download_url`: This is a signed URL that you can use to download the export file. **Note:** The result from a completed export task will expire after 24 hours. Hence, after 24 hours, you can no longer use the task ID associated with the task to generate a new download link. **Error Response** | Description | Name | Reason | Info | | --------------------------------------------- | --------------- | -------------------- | ---- | | When user export is disabled | `InternalError` | `UserExportDisabled` | - | | When the given ID does not refer to an export | `NotFound` | `TaskNotFound` | - | ## Download Export File The response of the check status endpoint will include a `download_url` field that contains a signed URL that you can open to download the [CSV](https://datatracker.ietf.org/doc/html/rfc4180) or [ndjson](https://github.com/ndjson/ndjson-spec) user export file. The signed URL is only valid for 60 seconds, and afterwards, you'll have to make another request to the **check status** endpoint using the **task ID** to obtain a new URL. ## Usage Example See the following guide for a detailed example of how to use the Export User API: {% content-ref url="../../admin-and-operations/user-management/export-users-using-the-user-export-api" %} [export-users-using-the-user-export-api](https://docs.authgear.com/admin-and-operations/user-management/export-users-using-the-user-export-api) {% endcontent-ref %}