Backend API Reference¶

You should prefer to use a library over the API directly. If a library for your language doesn't exist yet, please reach out to support@propelauth.com and we'll be happy to help.

Authentication¶

PropelAuth uses API keys for the backend API. You can manage your API key(s) under the Backend Integration section of your project at https://app.propelauth.com.

PropelAuth expects the API key in an Authorization header like the following:

Authorization: Bearer YOUR_API_KEY

Domain¶

PropelAuth uses a different domain for each application. Your application, for example, will be hosted at https://auth.yourdomain.com. An HTTP Request of /api/v1/example should be https://auth.yourdomain.com/api/v1/example in that case.

You can set your domain under the Go Live section of your project.

Fetch user by id¶

GET /api/backend/v1/user/{user_id}

Query Parameter	Description
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response:

{
    "user_id":            "e9d3520f-836e-403c-82c2-09843517e1ce", 
    "email":              "user@example.com",
    "email_confirmed":    true,
    "has_password":       true,

    "username":           "example", // (1)
    "first_name":         "first", // (2)
    "last_name":          "last", // (3)
    "picture_url":        "https://...", // (4)

    "locked":             false,
    "enabled":            true,
    "mfa_enabled":        false,

    "created_at":         1645131680,
    "last_active_at":     1650654711,

    // Only returned if include_orgs = true
    "org_id_to_org_info": { // (5)
        "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4" : {
            "org_id": "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4", 
            "org_name": "ExampleOrganization", 
            "user_role": "Owner"
        }
    },

    // Only returned if user was migrated from an external system 
    "legacy_user_id":    "507f191e810c19729de860ea"
}

Optional: Only returned if you have the field enabled as part of your user schema
Optional: Only returned if you have the field enabled as part of your user schema
Optional: Only returned if you have the field enabled as part of your user schema
Optional: Only returned if you have the field enabled as part of your user schema
Includes all organizations that the user is a member of

Fetch user by email¶

GET /api/backend/v1/user/email

Query Parameter	Description
email	The email address to look up
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response is the same as Fetch user by id.

Fetch user by username¶

GET /api/backend/v1/user/username

Query Parameter	Description
username	The username to look up
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response is the same as Fetch user by id.

Batch fetch users by ids¶

POST /api/backend/v1/user/user_ids

JSON Body Parameter	Description
user_ids	The user ids to look up

Query Parameter	Description
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response:

Any IDs that don't have a match are not returned. Duplicate users are only returned once.

[{
    "user_id":            "e9d3520f-836e-403c-82c2-09843517e1ce", 
    "email":              "user@example.com",
    "email_confirmed":    true,
    "has_password":       true,

    "username":           "example", // (1)
    "first_name":         "first", // (2)
    "last_name":          "last", // (3)
    "picture_url":        "https://...", // (4)

    "locked":             false,
    "enabled":            true,
    "mfa_enabled":        false,

    "created_at":         1645131680,
    "last_active_at":     1650654711,

    // Only returned if include_orgs = true
    "org_id_to_org_info": { // (5)
        "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4" : {
            "org_id": "2ef0e1fc-234f-4dc0-a50c-35adb1bbb7e4", 
            "org_name": "ExampleOrganization", 
            "user_role": "Owner"
        }
    },

    // Only returned if user was migrated from an external system 
    "legacy_user_id":    "507f191e810c19729de860ea"
}, {
  // Any other users that have a matching user_id
}]

Optional: Only returned if you have the field enabled as part of your user schema
Optional: Only returned if you have the field enabled as part of your user schema
Optional: Only returned if you have the field enabled as part of your user schema
Optional: Only returned if you have the field enabled as part of your user schema
Includes all organizations that the user is a member of

Batch fetch users by emails¶

POST /api/backend/v1/user/emails

JSON Body Parameter	Description
emails	The email addresses to look up

Query Parameter	Description
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response is the same as Batch fetch users by ids, but the keys are matching email addresses.

Batch fetch users by usernames¶

POST /api/backend/v1/user/usernames

JSON Body Parameter	Description
usernames	The usernames to look up

Query Parameter	Description
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response is the same as Batch fetch users by ids, but the keys are matching usernames.

Search for users¶

GET /api/backend/v1/user/query

Query Parameter	Description
page_size	The number of results to return at a time. Must be between 1 and 100, default 10.
page_number	Used to page over results
order_by	How to order the results. Must be one of: CREATED_AT_ASC, CREATED_AT_DESC, LAST_ACTIVE_AT_ASC, LAST_ACTIVE_AT_DESC, EMAIL, USERNAME
email_or_username	Searches for partial matches within email addresses or usernames. port would match a user with email address support@propelauth.com.
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response:

{
    "total_users": 103, 
    "current_page": 0, 
    "page_size": 10, 
    "has_more_results": true,
    "users": [{
        // See (1) for example users
    }, {
        // There will be 10 users in this response
    }]
}

Example user in response

Fetch users in organization¶

GET /api/backend/v1/user/org/{org_id}

Query Parameter	Description
page_size	The number of results to return at a time. Must be between 1 and 100, default 10.
page_number	Used to page over results
include_orgs	Whether or not to include the user's organization information in the response. Default false

Successful response:

{
    "total_users": 43, 
    "current_page": 0, 
    "page_size": 10, 
    "has_more_results": true,
    "users": [{
        // See (1) for example users
    }, {
        // There will be 10 users in this response, all in the specified organization
    }]
}

Example user in response

Create User¶

POST /api/backend/v1/user/

JSON Body Parameter	Description
email	The user's email address
email_confirmed	Whether the email address should start off as already confirmed. If false, the user is required to confirm the email address before they sign in.
send_email_to_confirm_email_address	Whether we should send an email immediately to confirm the user's email address. If false, the user will get a confirmation email when they first sign in.
password	Optional password. If unset, the user can set it themselves via their account page
username	Optional username. Can only be used if username is enabled in your user schema
first_name	Optional first name. Can only be used if name is enabled in your user schema
last_name	Optional last name. Can only be used if name is enabled in your user schema

Successful response:

{
    "user_id": "b5f667fb-e51a-49c6-a396-711e62948689"
}

Migrate User from External Source¶

Similar to Create User, but for cases where you already have a user. You can, for example, pass in a password hash for an existing user, and they will be able to login with their same password. It is also possible to provide an existing identifier, and we will store and return it along with our future identifiers, allowing you to link them.

POST /api/backend/v1/migrate_user/

JSON Body Parameter	Description
email	The user's email address
email_confirmed	Whether the email address should start off as already confirmed. If false, the user is required to confirm the email address before they sign in.
existing_user_id	(Optional) The user's ID in the existing system. This ID will be stored on the user as a `legacy_user_id` and it is present everywhere user_id's are (e.g. fetching user metadata or validating a user's token).
existing_password_hash	(Optional) The user's hashed password. We support both bcrypt and argon2 password hashes.
existing_mfa_base32_encoded_secret	(Optional) The user's MFA secret, base32 encoded. If specified the user will have MFA enabled by default.
enabled	(Optional) Whether or not the user can login
username	Optional username. Can only be used if username is enabled in your user schema
first_name	Optional first name. Can only be used if name is enabled in your user schema
last_name	Optional last name. Can only be used if name is enabled in your user schema

Successful response:

{
    "user_id": "b5f667fb-e51a-49c6-a396-711e62948689"
}

Create magic link¶

Creates a magic link that a user can use to log in. Use this API if you'd prefer to send the magic link to the customer yourself, otherwise, we have Create User which will email them directly.

POST /api/backend/v1/magic_link/

Argument	Description
email	The user's email address
redirect_to_url	(Optional) Where to redirect the user after they login. If unspecified, will use the login redirect path specified in your dashboard.
expires_in_hours	(Optional) How many hours should the link be valid for?
create_new_user_if_one_doesnt_exist	(Optional) If true, this will create a new user if one matching the provided email address doesn't exist. If false, the request will fail if no user with that email exists. Default is true.

Successful response:

{
    "url": "https://auth.yourdomain.com/..."
}

Update User Email¶

PUT /api/backend/v1/user/{user_id}/email

JSON Body Parameter	Description
new_email	New email address for this user
require_email_confirmation	Whether the new email address requires confirmation. If true, an email will be sent to the new email address to confirm. If false, the users email address will be updated and confirmed immediately.

Successful response:

{}

Update User Metadata¶

PUT /api/backend/v1/user/{user_id}

JSON Body Parameter	Description
username	Optional username. Can only be used if username is enabled in your user schema
first_name	Optional first name. Can only be used if name is enabled in your user schema
last_name	Optional last name. Can only be used if name is enabled in your user schema

Successful response:

{}

Delete user¶

DELETE /api/backend/v1/user/{user_id}

Successful response:

{}

Disable user¶

Afterwards, the user is logged out and unable to log back in.

POST /api/backend/v1/user/{user_id}/disable

Successful response:

{}

Enable user¶

Afterwards, the user is able to log in again.

POST /api/backend/v1/user/{user_id}/enable

Successful response:

{}

Fetch an organization¶

GET /api/backend/v1/org/{org_id}

Successful response:

{
    "org_id": "d488996d-8ccc-4101-b5f2-131f5f09ddb6"
    "name": "OneOfYourCustomers"
}

Fetch all organizations¶

GET /api/backend/v1/org/query

Query Parameter	Description
page_size	The number of results to return at a time. Must be between 1 and 100, default 10.
page_number	Used to page over results
order_by	How to order the results. Must be one of: CREATED_AT_ASC, CREATED_AT_DESC, NAME

Successful response:

{
    "total_orgs": 21, 
    "current_page": 0, 
    "page_size": 10, 
    "has_more_results": true,
    "orgs": [{
        "org_id": "d488996d-8ccc-4101-b5f2-131f5f09ddb6",
        "name": "OneOfYourCustomers"
    }, {
        // There will be 10 orgs in this response
    }]
}

Create Organization¶

POST /api/backend/v1/org/

JSON Body Parameter	Description
name	The organization's name

Successful response:

{
    "org_id": "d488996d-8ccc-4101-b5f2-131f5f09ddb6"
}

Update Org Metadata¶

PUT /api/backend/v1/org/{org_id}

JSON Body Parameter	Description
name	Organization name

Successful response:

{}

Add user to organization¶

POST /api/backend/v1/org/add_user

JSON Body Parameter	Description
user_id	The user's ID
org_id	The org's ID
role	The role of the user in that organization, e.g. Admin

Successful response:

{}

Allow organization to set up SAML connection¶

POST /api/backend/v1/org/{org_id}/allow_saml

Successful response:

{}

Disallow organization to set up SAML connection¶

POST /api/backend/v1/org/{org_id}/disallow_saml

Successful response:

{}

Fetch access token verification metadata¶

This endpoint fetches the metadata necessary to validate access tokens. The access tokens themselves are JWTs signed with RS256 (RSA Signature with SHA-256). The RS256 algorithm is more secure, and you can rotate keys quickly if they are compromised.

GET /api/backend/v1/token_verification_metadata

Successful response:

{
  // The public key you should use to the verify the access token
  "public_key_pem": "...",
}

Error Codes¶

Status Code	Description
400	The query is not valid.
401	Incorrect API key.
404	No results found.
426	Cannot use organizations unless B2B support is enabled. Enable it in your PropelAuth dashboard
429	Your app is making too many requests, too quickly.