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

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,

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

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

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.