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¶
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¶
Query Parameter | Description |
---|---|
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¶
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¶
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¶
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¶
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¶
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
}]
}
Fetch users in organization¶
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
}]
}
Create User¶
JSON Body Parameter | Description |
---|---|
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:
Update User 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¶
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¶
Successful response:
Fetch all organizations¶
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:
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. |