Authgear
Start BuildingHomePortalCommunity
  • Authgear Overview
  • Get Started
    • Start Building
    • 5-Minute Guide
    • Single-Page App
      • JavaScript (Web)
      • React
      • Angular
      • Vue
    • Native/Mobile App
      • iOS SDK
      • Android SDK
        • Android Kotlin coroutine support
        • Android OKHttp Interceptor Extension (Optional)
      • Flutter SDK
      • React Native SDK
      • Ionic SDK
      • Xamarin SDK
      • Using Authgear without SDK (Client side)
    • Regular Web App
      • Express
      • Next.js
      • Python Flask App
      • Java Spring Boot
      • ASP.NET Core MVC
      • Laravel
      • PHP
    • Backend/API Integration
      • Validate JWT in your application server
      • Forward Authentication to Authgear Resolver Endpoint
    • AI Coding tools
      • Cursor/Windsurf
  • How-To Guides
    • Authenticate
      • Add Passkeys Login
      • Add WhatsApp OTP Login
      • Add Email Magic Link Login
      • Add Biometric Login
      • Add Anonymous Users
      • Add authentication to any web page
      • Enable Two-Factor Authentication (2FA)
      • How to Use the OAuth 2.0 State Parameter
      • Reauthentication
      • How to Use Social/Enterprise Login Providers Without AuthUI
      • Passwordless Login for Apple App Store Review
      • Setup local development environment for Cookie-based authentication
      • Forgot/Reset Password settings
      • Phone number validation
      • Set Password Expiry
    • Single Sign-on
      • App2App Login
      • Pre-authenticated URLs
      • SSO between Mobile Apps / Websites
      • Force Authgear to Show Login Page
      • Single Sign-On with OIDC
      • Single Sign-On with SAML
        • Use Authgear as SAML Identity Provider for Salesforce
        • Use Authgear as SAML Identity Provider for Dropbox
        • SAML Attribute Mapping
    • Social Login / Enterprise Login Providers
      • Social Login Providers
        • Connect Apps to Apple
        • Connect Apps to Google
        • Connect Apps to Facebook
        • Connect Apps to GitHub
        • Connect Apps to LinkedIn
        • Connect Apps to WeChat
      • Enterprise Login Providers
        • Connect Apps to Azure Active Directory
        • Connect Apps to Microsoft AD FS
        • Connect Apps to Azure AD B2C
      • Force Social/Enterprise Login Providers to Show Login Screen
    • Built-in UI
      • Branding in Auth UI
      • User Settings
      • Privacy Policy & Terms of Service Links
      • Customer Support Link
      • Custom Text
    • Custom UI
      • Authentication Flow API
      • Implement Authentication Flow API using Express
      • Implement Authentication Flow API using PHP
      • Add Custom Login/Signup UI to Native Apps
      • Manually Link OAuth Provider using Account Management API
      • Implement a custom account recovery UI using Authentication Flow API
    • Integrate
      • Add custom fields to a JWT Access Token
      • User Analytics by Google Tag Manager
      • Track User Before and After Signup
      • Custom domain
      • Custom Email Provider
      • Custom SMS Provider
        • Twilio
        • Webhook/Custom Script
    • Monitor
      • Audit Log For Users Activities
      • Audit Log for Admin API and Portal
      • Analytics
    • User Management
      • Account Deletion
      • Import Users using User Import API
      • Export Users using the User Export API
      • Manage Users Roles and Groups
      • How to Handle Password While Creating Accounts for Users
    • User Profiles
      • What is User Profile
      • Access User Profiles
      • Update User Profiles
      • Profile Custom Attributes
      • Update user profile on sign-up using Hooks
    • Events and Hooks
      • Event List
      • Webhooks
      • JavaScript / TypeScript Hooks
      • Only Allow Signups from Inside the Corporate Network using Hooks
    • Mobile Apps
      • Use SDK to make authorized API calls to backend
      • Force authentication on app launch
      • Customize the Login Pop-up / Disable the login alert box
    • Languages and Localization
    • Custom Email and SMS Templates
    • Directly accessing Authgear Endpoint
    • Migration
      • Bulk migration
      • Rolling migration
      • Zero-downtime migration
    • Troubleshoot
      • How to Fix SubtleCrypto: digest() undefined Error in Authgear SDK
      • How to Fix CORS Error
  • Concepts
    • Identity Fundamentals
    • Authgear use cases
    • User, Identity and Authenticator
  • Security
    • Brute-force Protection
    • Bot Protection
    • Non-HTTP scheme redirect URI
    • Password Strength
  • Reference
    • APIs
      • Admin API
        • Authentication and Security
        • API Schema
        • Admin API Examples
        • Using global node IDs
        • Retrieving users using Admin API
        • User Management Examples
          • Search for users
          • Update user's standard attributes
          • Update user's picture
          • Generate OTP code
      • Authentication Flow API
      • OAuth 2.0 and OpenID Connect (OIDC)
        • UserInfo
        • Supported Scopes
      • User Import API
      • User Export API
    • Tokens
      • JWT Access Token
      • Refresh Token
    • Glossary
    • Billing FAQ
    • Rate Limits
      • Account Lockout
  • Client App SDKs
    • Javascript SDK Reference
    • iOS SDK Reference
    • Android SDK Reference
    • Flutter SDK Reference
    • Xamarin SDK Reference
  • Deploy on your Cloud
    • Running locally with Docker
    • Deploy with Helm chart
    • Authenticating HTTP request with Nginx
    • Configurations
      • Environment Variables
      • authgear.yaml
      • authgear.secrets.yaml
    • Reference Architecture Diagrams
      • Google Cloud Reference Architecture
      • Azure Reference Architecture
      • AWS Reference Architecture
      • Throughput Scaling Reference
Powered by GitBook
On this page
  • Authentication
  • Endpoints
  • Initiate Export Task
  • Check Status
  • Download Export File
  • Usage Example

Was this helpful?

Edit on GitHub
  1. Reference
  2. APIs

User Export API

API Reference for the User Export API

PreviousUser Import APINextTokens

Last updated 5 months ago

Was this helpful?

The User Export API allows developers to bulk export users into a or 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 .

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

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 <Admin API JWT Token>

Host

<Your Authgear Project domain>

Body

The Initiate Export endpoint accepts JSON input via an HTTP(S) request body. The following is an example of the input:

{
  "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

Array

/groups

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:

{"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:

{
    "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"
                    }
                ]
            }
        }
    }
}
Forbidden
  • 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 <Admin API JWT Token>

Host

<Your Authgear Project domain>

Response

The following is what the response body of the Check Status endpoint looks like:

{
    "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"
    }
}
Forbidden
  • 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 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:

a list of all the assigned to the current user.

a list of all the access management the user has been added to.

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 or user export file.

CSV
ndjson
Admin API JWT token
CSV
ndjson
Export Users using the User Export API
roles
groups