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,

    "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"
        }
    }
}
  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,

    "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"
        }
    }
}, {
  // 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"
}

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:

{}

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
    }]
}

Fetch access token verification metadata

This endpoint fetches the metadata necessary to validate access tokens. The access tokens themselves are JWTs signed with RS256.

GET /api/backend/v1/token_verification_metadata

Successful response:

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

Errors

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.