openapi: 3.1.0
info:
title: PropelAuth Organization API
description: |
Backend REST API for managing tenants (organizations) in PropelAuth. Create and update
organizations, add and remove members, invite users, change roles, manage role mappings,
and revoke pending invites. All endpoints require a PropelAuth Backend Integration API key
presented as a Bearer token.
version: "1.0.0"
contact:
name: PropelAuth Support
url: https://www.propelauth.com
email: [email protected]
license:
name: PropelAuth Terms
url: https://www.propelauth.com/legal/terms-of-service
servers:
- url: https://{authId}.propelauthtest.com
description: Test environment
variables:
authId:
default: "0000000000"
- url: https://auth.example.com
description: Production / Staging custom domain
security:
- BackendApiKey: []
tags:
- name: Organizations
description: Create, read, update, and delete tenant organizations
- name: Members
description: Add, remove, invite, and change roles for users within an organization
- name: Role Mappings
description: Manage custom role mappings per organization
- name: Invites
description: Inspect and revoke pending organization invites
paths:
/api/backend/v1/org/:
post:
summary: Create Org
description: Create a new organization (tenant).
operationId: createOrg
tags: [Organizations]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrgRequest'
responses:
'201':
description: Org created
content:
application/json:
schema:
$ref: '#/components/schemas/Org'
/api/backend/v1/org/{orgId}:
get:
summary: Fetch Org
description: Get an organization by ID.
operationId: fetchOrg
tags: [Organizations]
parameters:
- $ref: '#/components/parameters/OrgId'
responses:
'200':
description: Org found
content:
application/json:
schema:
$ref: '#/components/schemas/Org'
put:
summary: Update Org
description: Update mutable organization fields.
operationId: updateOrg
tags: [Organizations]
parameters:
- $ref: '#/components/parameters/OrgId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateOrgRequest'
responses:
'200':
description: Org updated
delete:
summary: Delete Org
description: Permanently delete an organization.
operationId: deleteOrg
tags: [Organizations]
parameters:
- $ref: '#/components/parameters/OrgId'
responses:
'200':
description: Org deleted
/api/backend/v1/org/query:
post:
summary: Fetch Orgs
description: Page through organizations with optional filters and ordering.
operationId: fetchOrgs
tags: [Organizations]
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
page_size: { type: integer, default: 10 }
page_number: { type: integer, default: 0 }
order_by:
type: string
enum: [CREATED_AT_ASC, CREATED_AT_DESC, NAME]
name: { type: string, description: Filter by org name substring }
responses:
'200':
description: Page of orgs
content:
application/json:
schema:
$ref: '#/components/schemas/OrgPage'
/api/backend/v1/user/org/{orgId}:
get:
summary: Fetch Users In Org
description: List users that belong to the supplied organization.
operationId: fetchUsersInOrg
tags: [Members]
parameters:
- $ref: '#/components/parameters/OrgId'
- name: page_size
in: query
schema: { type: integer, default: 10 }
- name: page_number
in: query
schema: { type: integer, default: 0 }
- name: role
in: query
schema: { type: string }
responses:
'200':
description: Page of users
content:
application/json:
schema:
$ref: '#/components/schemas/UserPage'
/api/backend/v1/org/add_user:
post:
summary: Add User To Org
description: Add an existing user to an organization with a specified role.
operationId: addUserToOrg
tags: [Members]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [user_id, org_id, role]
properties:
user_id: { type: string, format: uuid }
org_id: { type: string, format: uuid }
role: { type: string }
additional_roles:
type: array
items: { type: string }
responses:
'200':
description: User added
/api/backend/v1/invite_user:
post:
summary: Invite User To Org
description: Send an invite email for a user to join an organization.
operationId: inviteUserToOrg
tags: [Invites]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, org_id, role]
properties:
email: { type: string, format: email }
org_id: { type: string, format: uuid }
role: { type: string }
additional_roles:
type: array
items: { type: string }
responses:
'200':
description: Invite sent
/api/backend/v1/invite_user_by_id:
post:
summary: Invite User To Org By User ID
description: Invite an existing user (by ID) into an organization.
operationId: inviteUserToOrgById
tags: [Invites]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [user_id, org_id, role]
properties:
user_id: { type: string, format: uuid }
org_id: { type: string, format: uuid }
role: { type: string }
responses:
'200':
description: Invite created
/api/backend/v1/org/change_role:
post:
summary: Change Role
description: Change a user's role within an organization.
operationId: changeRole
tags: [Members]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [user_id, org_id, role]
properties:
user_id: { type: string, format: uuid }
org_id: { type: string, format: uuid }
role: { type: string }
additional_roles:
type: array
items: { type: string }
responses:
'200':
description: Role updated
/api/backend/v1/org/remove_user:
post:
summary: Remove User From Org
description: Remove a user from an organization.
operationId: removeUserFromOrg
tags: [Members]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [user_id, org_id]
properties:
user_id: { type: string, format: uuid }
org_id: { type: string, format: uuid }
responses:
'200':
description: User removed
/api/backend/v1/custom_role_mappings:
get:
summary: Fetch Role Mappings
description: List custom role mappings configured for your project.
operationId: fetchRoleMappings
tags: [Role Mappings]
responses:
'200':
description: Role mappings
content:
application/json:
schema:
type: object
properties:
custom_role_mappings:
type: array
items: { $ref: '#/components/schemas/RoleMapping' }
/api/backend/v1/pending_org_invites:
get:
summary: Fetch Pending Invites
description: Page through pending invites for an organization or across the whole project.
operationId: fetchPendingInvites
tags: [Invites]
parameters:
- name: org_id
in: query
schema: { type: string, format: uuid }
- name: page_size
in: query
schema: { type: integer, default: 10 }
- name: page_number
in: query
schema: { type: integer, default: 0 }
responses:
'200':
description: Pending invites
content:
application/json:
schema:
type: object
properties:
invites:
type: array
items: { $ref: '#/components/schemas/PendingInvite' }
total_invites: { type: integer }
has_more_results: { type: boolean }
delete:
summary: Revoke Pending Org Invite
description: Revoke a pending invite.
operationId: revokePendingOrgInvite
tags: [Invites]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [org_id, invitee_email]
properties:
org_id: { type: string, format: uuid }
invitee_email: { type: string, format: email }
responses:
'200':
description: Invite revoked
components:
securitySchemes:
BackendApiKey:
type: http
scheme: bearer
parameters:
OrgId:
name: orgId
in: path
required: true
schema: { type: string, format: uuid }
schemas:
Org:
type: object
properties:
org_id: { type: string, format: uuid }
name: { type: string }
url_safe_org_name: { type: string }
is_saml_configured: { type: boolean }
is_saml_in_test_mode: { type: boolean }
max_users: { type: integer }
metadata:
type: object
additionalProperties: true
domain: { type: string }
domain_autojoin: { type: boolean }
domain_restrict: { type: boolean }
legacy_org_id: { type: string }
custom_role_mapping_name: { type: string }
can_setup_saml: { type: boolean }
created_at: { type: integer }
OrgPage:
type: object
properties:
orgs:
type: array
items: { $ref: '#/components/schemas/Org' }
total_orgs: { type: integer }
current_page: { type: integer }
page_size: { type: integer }
has_more_results: { type: boolean }
UserPage:
type: object
properties:
users:
type: array
items:
type: object
additionalProperties: true
total_users: { type: integer }
current_page: { type: integer }
page_size: { type: integer }
has_more_results: { type: boolean }
CreateOrgRequest:
type: object
required: [name]
properties:
name: { type: string }
domain: { type: string }
enable_auto_joining_by_domain: { type: boolean }
members_must_have_matching_domain: { type: boolean }
max_users: { type: integer }
custom_role_mapping_name: { type: string }
legacy_org_id: { type: string }
UpdateOrgRequest:
type: object
properties:
name: { type: string }
can_setup_saml: { type: boolean }
max_users: { type: integer }
metadata:
type: object
additionalProperties: true
domain: { type: string }
require_2fa_by: { type: integer }
extra_domains:
type: array
items: { type: string }
custom_role_mapping_name: { type: string }
RoleMapping:
type: object
properties:
custom_role_mapping_name: { type: string }
num_orgs_subscribed: { type: integer }
roles:
type: array
items:
type: object
properties:
name: { type: string }
description: { type: string }
is_internal: { type: boolean }
is_visible_to_end_user: { type: boolean }
permissions:
type: array
items: { type: string }
PendingInvite:
type: object
properties:
invitee_email: { type: string, format: email }
org_id: { type: string, format: uuid }
org_name: { type: string }
role_in_org: { type: string }
additional_roles_in_org:
type: array
items: { type: string }
created_at: { type: integer }
expires_at: { type: integer }
inviter_email: { type: string, format: email }
inviter_user_id: { type: string, format: uuid }