Skip to content

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"
}
  1. Optional: Only returned if you have the field enabled as part of your user schema
  2. Optional: Only returned if you have the field enabled as part of your user schema
  3. Optional: Only returned if you have the field enabled as part of your user schema
  4. Optional: Only returned if you have the field enabled as part of your user schema
  5. 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
}]
  1. Optional: Only returned if you have the field enabled as part of your user schema
  2. Optional: Only returned if you have the field enabled as part of your user schema
  3. Optional: Only returned if you have the field enabled as part of your user schema
  4. Optional: Only returned if you have the field enabled as part of your user schema
  5. 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
    }]
}
  1. 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
    }]
}
  1. 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"
}

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.