Management API v1 (deprecated)

WARNING: This version of the Management API has been deprecated. Please use the new version instead.

Authentication

POST /oauth/token
Obtain a token to call the API

Auth0 API requires an access_token. You can get one by authenticating with your client_id and client_secret (It will be valid for 24 hours). To obtain the global client ID and global client secret see the "Advanced" section under "Account Settings" in the Auth0 dashboard.

POST /oauth/token
Content-Type: application/json
{
  "client_id": "",
  "client_secret": "",
  "grant_type": "client_credentials"
}

Once authenticated, the access_token can be included in the request as part of the querystring ( ?access_token=...) or in an HTTP header (Authorization: Bearer ...access_token...).

Users

GET /api/users
Gets all users who have logged in

Gets all users who have logged in through any of your connections.

GET /api/users
Authorization: Bearer {token}
GET /api/users?search={query}
Search users

Performs a 'starts with' search by name or email. Or search by field, for example: email_verified:true; loginsCount:1; family_name:"johnson"

GET /api/users?search={query}
Authorization: Bearer {token}
GET /api/users/{user_id}
Gets an user by id

Gets an user who have logged in through any of your connections that has a given id.

GET /api/users/{user_id}
Authorization: Bearer {token}
GET /api/users/{user_id}/devices
Gets all user's devices

Gets all devices/refresh_tokens being used by the user.

GET /api/users/{user_id}/devices
Authorization: Bearer {token}
GET /api/connections/{connection}/users
Gets all users from an enterprise directory

Head ups! If the connection does not support querying for users (for instance ADFS, SAMLP), it will return the users who have logged in through that connection.

GET /api/connections/{connection}/users
Authorization: Bearer {token}
GET /api/connections/{connection}/users?search={criteria}
Search users from an enterprise directories

Search remarks: Depending on the connection's type the search will be done in different fields:

  • Active Directory/LDAP: by default uses Ambigous name resolution (ANR) which expands to givenName (first name), sn (surname, or last name), displayName, RDN, legacyExchangeDN, physicalDeliveryOfficeName (for example, Building A, Suite 1234), proxyAddresses (the collection of e-mail addresses over all e-mail address spaces that the Exchange server knows about).
  • Database Connections (not custom): Name/Email case insensitive.
  • Google Apps: Email/username case insensitive.
  • WAAD/WAAD2: Name/Email case insensitive.
  • Windows Azure Active Directory or Office365: name/email case insensitive Heads up! If the connection does not support querying for users (for instance ADFS, SAMLP), it will return the users who have logged in through that connection.
GET /api/connections/{connection}/users?search={query}&per_page={count}
Authorization: Bearer {token}
GET /api/enterpriseconnections/users?search={criteria}
Search users from all enterprise directories

Search users from all enterprise directories based on the specified criteria. The parameter is mandatory. Search remarks: Depending on the connection's type the search will be done in different fields:

  • Active Directory/LDAP: by default uses Ambigous name resolution (ANR) which expands to givenName (first name), sn (surname, or last name), displayName, RDN, legacyExchangeDN, physicalDeliveryOfficeName (for example, Building A, Suite 1234), proxyAddresses (the collection of e-mail addresses over all e-mail address spaces that the Exchange server knows about).
  • Database Connections (not custom): Name/Email case insensitive.
  • Google Apps: Email/username case insensitive.
  • WAAD/WAAD2: Name/Email case insensitive.
  • Windows Azure Active Directory or Office365: name/email case insensitive Heads up! If the connection does not support querying for users (for instance ADFS, SAMLP), it will return the users who have logged in through that connection.
GET /api/enterpriseconnections/users?search=&per_page=
Authorization: Bearer {token}
GET /api/socialconnections/users?search={criteria}
Gets all users who have logged in with social connections that match the search criteria

Gets all users who have logged in through social connections that match the specified search criteria. Performs a 'starts with' search by name or email. Or searches by field, for example: email_verified:true; loginsCount:1; family_name:"johnson"

GET /api/socialconnections/users?search=&per_page=
Authorization: Bearer {token}
GET /api/clients/{client-id}/users
Gets all users from a specific client

Gets all users who have logged in with a specific client

GET /api/clients//users
Authorization: Bearer {token}
POST /api/users
Creates a user

Creates a user. The body of the request must include the email, the password, and the connection of the user. Also it can include the user's email_verified parameter and the extra attributes that you want to add.

POST /api/users/
Authorization: Bearer {token}
Content-Type: application/json
{
  "email":          "",
  "password":       "",
  "connection":     "", // only database or passwordless connections
  "email_verified": falsetrue, // if true, it won't send an email for confirmation
  "vip": true,
  "birthdate": "1980-12-23T03:00:00.000Z"
}
POST /api/users/{user_id}/send_verification_email
Resends verification account email
Resends verification account email.
POST /api/users//`send_verification_email`
Authorization: Bearer {token}
POST /api/users/{user_id}/change_password_ticket
Generates change password ticket

Generates change password ticket. The body of the request must include the newPassword of the user. Optionally, you can include the resultUrl (post verification url).

POST /api/users/{user_id}/change_password_ticket
Authorization: Bearer {token}
Content-Type: application/json
{
  "newPassword":    "",
  "resultUrl":      "" // optional
}
POST /api/users/{user_id}/verification_ticket
Generates verification account ticket

Generates verification account ticket. Optionally, you can include the resultUrl (post verification url) in the body of the request.

POST /api/users/{user_id}/verification_ticket
Authorization: Bearer {token}
Content-Type: application/json
{
  "resultUrl":      "" // optional
}
POST /api/users/{user_id}/publickey
Saves user public key for specified device

Saves user public key for specified device.

POST /api/users//publickey
Authorization: Bearer {token}
Content-Type: application/json
{
  "device":     "",
  "public_key": ""
}
PUT /api/users/{user_id}/email
Updates user email

Update user email. The body of the request must include the new email.

PUT /api/users/{user_id}/email
Authorization: Bearer {token}
Content-Type: application/json
{
  "email":   "",
  "verify":  truefalse // if false, it won't send an email for verification
}
PUT /api/users/{user_id}/metadata
Updates user metadata

Update user metadata. The body of the request must include a json object with metadata attributes.

PUT /api/users/{user_id}/metadata
Authorization: Bearer {token}
Content-Type: application/json
{
  "Policy": "1238907654",
  "Customer Id": "1234"
}
PUT /api/users/{user_id}/password
Updates user password

Update user password. The body of the request must include the new password.

PUT /api/users/{user_id}/password
Authorization: Bearer {token}
Content-Type: application/json
{
  "password":   "",
  "verify":     truefalse, // if false, it won't send an email for confirmation
}
PUT /api/users/{email}/password
Updates user password

Update user password. The body of the request must include the email, connection and the new password.

PUT /api/users/{email}/password
Authorization: Bearer {token}
Content-Type: application/json
{
  "email":      "",
  "password":   "",
  "connection": "
  ", // only database connections
  "verify":     truefalse, // if false, it won't send an email for confirmation
}
PATCH /api/users/{user_id}/metadata
Patch user metadata

Patch user metadata. The body of the request must include a json object with metadata attributes. It will not override metadata not specified attributes.

PATCH /api/users/{user_id}/metadata
Authorization: Bearer {token}
Content-Type: application/json
{
  "Policy": "1238907654",
  "Customer Id": "1234"
}
DELETE /api/users/{user_id}
Deletes a user

Deletes a user identified by user_id

DELETE /api/users/{user_id}
Authorization: Bearer {token}
DELETE /api/users/{user_id}/refresh_tokens/{refresh_token}
Revokes a refresh token

Revokes a user's refresh token

DELETE /api/users/{user_id}/refresh_tokens/{refresh_token}
Authorization: Bearer {token}
DELETE /api/users/{user_id}/publickey?device={device}
Revokes a public key

Revokes a user's public key for specified device

DELETE /api/users/{user_id}/publickey?device={device}
Authorization: Bearer {token}

Connections

GET /api/connections
Gets all connections

Gets a list of all the connections (enterprise and social) and all its options

GET /api/connections
Authorization: Bearer {token}
GET /api/connections/{connection-name}
Gets one connection by name

Gets a connection by name (enterprise and social) and all its options

GET /api/connections/{connection-name}
Authorization: Bearer {token}
DELETE /api/connections/{connection-name}
Removes a connection

Deletes a connection identified by connectionName

DELETE /api/connections/{connection-name}
Authorization: Bearer {token}
POST /api/connections
Creates a connection

Creates a connection. The body of the request must include the name, the authentication strategy to use, and an options object with the connection parameters.

POST /api/connections
Authorization: Bearer {token}
Content-Type: application/json
{
  "name":     ""
  "strategy": "waad|google-apps|adfs|PingFederate|samlp|auth0|etc",
  "options":   {
    "tenant_domain":
    "domain_aliases":
    "tenant_domain":
    "domain_aliases":
    "tenant_domain": ,
    "domain_aliases": ,
    "adfs_server":
    "domain_aliases": ,
    "PingFederate Base URL": ,
    "Signing Cert":   "",
    "signInEndpoint":   "",
    "signingCert":   "",
    "tenant_domain": "",
    "domain_aliases": ,
    "signOutEndpoint":  "",
  }
}
PUT /api/connections/{connection-name}
Updates a connection

Updates a connection. The body of the request must include the options object with the connection parameters and the status. The request's body depends on the strategy that was used to create the connection. Select a strategy: waad google-apps adfs PingFederate samlp auth0

PUT /api/connections/{connection-name}
Authorization: Bearer {token}
Content-Type: application/json
{
  "options":   {
    "tenant_domain":
    "tenant_domain":
    "tenant_domain": ,
    "adfs_server":
    "PingFederate Base URL": ,
    "Signing Cert":   "",
    "signInEndpoint":   "",
    "signingCert":   "",
    "tenant_domain": "",
    "signOutEndpoint":  "",
  }
  "status": true|false
}

Clients

GET /api/clients
Gets all applications/APIs

Gets a list of all the applications/APIs (aka clients) and all its options

GET /api/clients
Authorization: Bearer {token}
POST /api/clients
Creates a new applications/APIs

Create a client. The body of the request can include the name and callbacks parameters.

POST /api/clients
Authorization: Bearer {token}
Content-Type: application/json
{
  "name":      "",
  "callbacks": "" // You can specify multiple valid URLs by comma-separating them.
}
PATCH /api/clients/{client-id}
Updates an applications/APIs

Update a client. The body of the request must include the name and callbacks parameters. Does not overwrite the entire client, only the provided values. Additionally the signingKey can be overwritten using this method (not provided for trial for safety reasons). Possible formats are:

  • "signingKey": { cert: "%CERT_STRING%" } // using a cert
  • "signingKey": { key: "%KEY_STRING%" } // using a private key
  • "signingKey": { pkcs7: "%PKCS7_STRING%" } // using a pkcs7

WARNING! Changing the signingKey for the globalClient will change it for all clients.

PATCH /api/clients/{client-id}
Authorization: Bearer {token}
Content-Type: application/json
{
  "name":      "",
  "callbacks": "" // You can specify multiple valid URLs by comma-separating them.
}

Rules

GET /api/rules
Gets all rules

Gets a list of all the rules

GET /api/rules
Authorization: Bearer {token}
POST /api/rules
Creates a new applications/APIs

Create a rule. The body of the request must include the name, status and script parameters.

POST /api/rules/
Authorization: Bearer {token}
Content-Type: application/json
{
  "name":     "",
  "status":   true|false,
  "script":   "function (user, context, callback) { user.foo = 'bar'; callback(null, user, context);}"
               // new lines should be encoded as \n
  "order": 1 // optional
}
PUT /api/rules/{rule-name}
Updates a rule

Update a rule. The body of the request must include the status and script parameters.

PUT /api/rules/{rule-name}
Authorization: Bearer {token}
Content-Type: application/json
{
  "status":   true|false,
  "script":   "function (user, context, callback) { user.foo = 'bar'; callback(null, user, context);}"
               // new lines should be encoded as \n
  "order": 1 // optional
}
DELETE /api/rules/{rule-name}
Deletes a rules

Deletes a rule identified by rule-name (url-encoded)

DELETE /api/rules/{rule-name}
Authorization: Bearer {token}

Email Templates

GET /api/emails/{email-template-name}
Gets an email template by name

Gets an email template by name

GET /api/emails/{email-template-name}
Authorization: Bearer {token}

Template Names:

  • verify_email
  • welcome_email
  • reset_email
  • blocked_account
POST /api/emails
Creates an email template

Creates an email template. The body of the request must include the template name and the tenant.

POST /api/emails/
Authorization: Bearer {token}
Content-Type: application/json
{
  "template": "template_name",
  "disabled": true|false,
  "from": "",
  "subject": "",
  "body": "",
  "urlLifetimeInSeconds": "",
  "resultUrl": "",
  "syntax": "liquid"
}

Template Names:

  • verify_email
  • welcome_email
  • reset_email
  • blocked_account
PUT /api/emails/{email-template-name}
Updates an email template

Updates an email template.

PUT /api/emails/{email-template-name}
Authorization: Bearer {token}
Content-Type: application/json
{
  "disabled": true|false,
  "from": "",
  "subject": "",
  "body": "",
  "urlLifetimeInSeconds": "",
  "resultUrl": "",
  "syntax": "liquid"
}

Template Names:

  • verify_email
  • welcome_email
  • reset_email
  • blocked_account

Logs

GET /api/logs/{_id}
Gets a log entry

Retrieves the data related to the log entry identified by _id.

GET /api/logs/{_id}
Authorization: Bearer {token}
GET /api/users/{user_id}/logs?page={number}&per_page={items}
Gets the logs for a particular user

Retrieves the log entries related to the user identified by user_id. Log entries are split into pages of a particular size to avoid returning all data at once:

  • page: The page number. Zero based.
  • items: The amount of entries per page.
GET /api/users/{user_id}/logs?page={number}&per_page={items}
Authorization: Bearer {token}

Response fields

The following is a description of the values returned by the request:

  • start: The absolute number (considering all log entries) of the first entry in the page.
  • length: The amount of entries in the page (can only be different than limit in the last page).
  • total: The amount of entries in the page.
  • limit: The maximum amount of items in a page.
  • logs: A collection of log entries.
    • date: The moment when the event occured.
    • connection: The connection related to the event.
    • client_id: The id of the client related to the event.
    • client_name: The name of the client related to the event.
    • ip: The IP address from where the request that caused the log entry originated.
    • user_id: The user id releated to the event.
    • user_name: The user name releated to the event.
    • description: The event's description.
    • user_agent: The user agent that was used to cause the creation of the log entry.
    • type: An abbreviation of the event type. Refer to the event acronym mappings below for the mapping between abbreviations and their meaning.
    • details: Additional (and very useful) details about the event. They don't have a specific schema as they vary based on event type.
Event acronym mappings

The following is the meaning of the event acronyms:

  • s:Success Login
  • f:Failed Login
  • fu:Failed Login (invalid email/username)
  • fp:Failed Login (wrong password)
  • fc:Failed by Connector
  • fco:Failed by CORS
  • con:Connector Online
  • coff:Connector Offline
  • ss:Success Signup
  • fs:Failed Signup
  • sv:Success Verification Email
  • fv:Failed Verification Email
  • scp:Success Change Password
  • fcp:Failed Change Password
  • sce:Success Change Email
  • fce:Failed Change Email
  • svr:Success Verification Email Request
  • fvr:Failed Verification Email Request
  • scpr:Success Change Password Request
  • fcpr:Failed Change Password Request
  • fn:Failed Sending Notification
GET /api/logs?page={number}&per_page={items}&sort={field}:{-1|1}&fields={fields}&exclude_fields{true|false}
Gets log entries

Retrieves data about log entries based on the specified parameters. Log entries are split into pages of a particular size to avoid returning all data at once:

  • page: The page number. Zero based.
  • items: The amount of entries per page.
  • field: The field to use for sorting. 1 == ascending and -1 == descending.
  • fields: Can be used to either include or exclude the specified fields by providing a comma (,) separated list of fields, for example at,c,cn,un. If no list is provided all fields are included in the response.
  • exclude_fields: To exclude the fields exclude_fields=true must be used (if not specified it defaults to false). Possible values for field are:
  • date: The moment when the event occured.
  • connection: The connection related to the event.
  • client_name: The name of the client related to the event.
  • user_name: The user name releated to the event.
GET /api/logs?page={number}&per_page={items}&sort={field}:{-1|1}&fields={fields}&exclude_fields{true|false}
Authorization: Bearer {token}

Response fields

The following is a description of the values returned by the request:

  • start: The absolute number (considering all log entries) of the first entry in the page.
  • length: The amount of entries in the page (can only be different than limit in the last page).
  • total: The amount of entries in the page.
  • limit: The maximum amount of items in a page.
  • logs: A collection of log entries.
    • date: The moment when the event occured.
    • connection: The connection related to the event.
    • client_id: The id of the client related to the event.
    • client_name: The name of the client related to the event.
    • ip: The IP address from where the request that caused the log entry originated.
    • user_id: The user id releated to the event.
    • user_name: The user name releated to the event.
    • description: The event's description.
    • user_agent: The user agent that was used to cause the creation of the log entry.
    • type: An abbreviation of the event type. Refer to the event acronym mappings below for the mapping between abbreviations and their meaning.
    • details: Additional (and very useful) details about the event. They don't have a specific schema as they vary based on event type.
Event acronym mappings

The following is the meaning of the event acronyms:

  • s:Success Login
  • f:Failed Login
  • fu:Failed Login (invalid email/username)
  • fp:Failed Login (wrong password)
  • fc:Failed by Connector
  • fco:Failed by CORS
  • con:Connector Online
  • coff:Connector Offline
  • ss:Success Signup
  • fs:Failed Signup
  • sv:Success Verification Email
  • fv:Failed Verification Email
  • scp:Success Change Password
  • fcp:Failed Change Password
  • sce:Success Change Email
  • fce:Failed Change Email
  • svr:Success Verification Email Request
  • fvr:Failed Verification Email Request
  • scpr:Success Change Password Request
  • fcpr:Failed Change Password Request
  • fn:Failed Sending Notification
GET /api/logs?search={criteria}
Gets log entries

Retrieves logs that match the specified search criteria. This parameter can be combined with all the others in the /api/logs endpoint but is specified separately for clarity. If no fields are provided a case insensitive 'starts with' search is performed on all of the following fields:

  • client_name
  • connection
  • user_name

Otherwise, you can specify multiple fields and specify the search using the %field%:%search%, for example: application:node user:"John@contoso.com". Values specified without quotes are matched using a case insensitive 'starts with' search. If quotes are used a case insensitve exact search is used. If multiple fields are used, the AND operator is used to join the clauses.

Available Fields
  • application: Maps to the client_name field.
  • connection: Maps to the connection field.
  • user: Maps to the user_name field.
GET /api/logs?search={criteria}
Authorization: Bearer {token}

Response fields

The following is a description of the values returned by the request:

  • start: The absolute number (considering all log entries) of the first entry in the page.
  • length: The amount of entries in the page (can only be different than limit in the last page).
  • total: The amount of entries in the page.
  • limit: The maximum amount of items in a page.
  • logs: A collection of log entries.
    • date: The moment when the event occured.
    • connection: The connection related to the event.
    • client_id: The id of the client related to the event.
    • client_name: The name of the client related to the event.
    • ip: The IP address from where the request that caused the log entry originated.
    • user_id: The user id releated to the event.
    • user_name: The user name releated to the event.
    • description: The event's description.
    • user_agent: The user agent that was used to cause the creation of the log entry.
    • type: An abbreviation of the event type. Refer to the event acronym mappings below for the mapping between abbreviations and their meaning.
    • details: Additional (and very useful) details about the event. They don't have a specific schema as they vary based on event type.
Event acronym mappings

The following is the meaning of the event acronyms:

  • s:Success Login
  • f:Failed Login
  • fu:Failed Login (invalid email/username)
  • fp:Failed Login (wrong password)
  • fc:Failed by Connector
  • fco:Failed by CORS
  • con:Connector Online
  • coff:Connector Offline
  • ss:Success Signup
  • fs:Failed Signup
  • sv:Success Verification Email
  • fv:Failed Verification Email
  • scp:Success Change Password
  • fcp:Failed Change Password
  • sce:Success Change Email
  • fce:Failed Change Email
  • svr:Success Verification Email Request
  • fvr:Failed Verification Email Request
  • scpr:Success Change Password Request
  • fcpr:Failed Change Password Request
  • fn:Failed Sending Notification
GET /api/logs?from={checkpointId}&take={count}
Gets log entries from a checkpoint

Retrieves count log entries that were logged after checkpointId.

  • If checkpointId is not provided it will start retrieving from the first log entry.
  • If count is not provided the default value is 200 (also the max value).
GET /api/logs?from={checkpointId}&take={count}
Authorization: Bearer {token}

Response fields

The following is a description of the values returned by the request:

  • start: The absolute number (considering all log entries) of the first entry in the page.
  • length: The amount of entries in the page (can only be different than limit in the last page).
  • total: The amount of entries in the page.
  • limit: The maximum amount of items in a page.
  • logs: A collection of log entries.
    • date: The moment when the event occured.
    • connection: The connection related to the event.
    • client_id: The id of the client related to the event.
    • client_name: The name of the client related to the event.
    • ip: The IP address from where the request that caused the log entry originated.
    • user_id: The user id releated to the event.
    • user_name: The user name releated to the event.
    • description: The event's description.
    • user_agent: The user agent that was used to cause the creation of the log entry.
    • type: An abbreviation of the event type. Refer to the event acronym mappings below for the mapping between abbreviations and their meaning.
    • details: Additional (and very useful) details about the event. They don't have a specific schema as they vary based on event type.
Event acronym mappings

The following is the meaning of the event acronyms:

  • s:Success Login
  • f:Failed Login
  • fu:Failed Login (invalid email/username)
  • fp:Failed Login (wrong password)
  • fc:Failed by Connector
  • fco:Failed by CORS
  • con:Connector Online
  • coff:Connector Offline
  • ss:Success Signup
  • fs:Failed Signup
  • sv:Success Verification Email
  • fv:Failed Verification Email
  • scp:Success Change Password
  • fcp:Failed Change Password
  • sce:Success Change Email
  • fce:Failed Change Email
  • svr:Success Verification Email Request
  • fvr:Failed Verification Email Request
  • scpr:Success Change Password Request
  • fcpr:Failed Change Password Request
  • fn:Failed Sending Notification