openapi: 3.0.3
info:
title: One-Time Login Applications Users API
description: Login users using one-time login methods like magic links or OTPs. This implements a backend-to-backend integration for authentication.
version: ''
servers:
- url: https://api.sbx.transmitsecurity.io/cis
description: Sandbox environment
- url: https://api.transmitsecurity.io/cis
description: Production environment (US)
- url: https://api.eu.transmitsecurity.io/cis
description: Production environment (EU)
- url: https://api.ca.transmitsecurity.io/cis
description: Production environment (CA)
- url: https://api.au.transmitsecurity.io/cis
description: Production environment (AU)
security: []
tags:
- name: Users
paths:
/v1/users/count:
get:
operationId: getUsersCount
summary: Get users count
description: 'Get the number of saved users. <br><br>**Required permissions**: `users:list`, `apps:list`, `[appId]:list`.'
parameters:
- name: search
required: false
in: query
description: Search expression based on the [SCIM protocol](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2). For syntax and searchable fields, see [Search query syntax](/openapi/scim_search_syntax/)
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUsersCount
type: object
required:
- result
description: Number of users
properties:
result:
$ref: '#/components/schemas/ApiUsersCount'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users:
post:
operationId: createUser
summary: Create user
description: 'Add a user to Transmit. A user_id is returned as part of the User in the response that can then be used to perform other operations, such as get, update and delete. An email or a phone_number are required. <br><br>**Required permissions**: `apps:create`, `[appId]:create`, `users:create`.'
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiCreateUserInput'
responses:
'201':
description: ''
content:
application/json:
schema:
title: ApiCreatedResponse-createUser
type: object
required:
- result
description: The user has been successfully created.
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/IdentifierIsTakenHttpError'
security:
- ClientAccessToken: []
tags:
- Users
get:
operationId: getUsers
summary: Get users
description: 'Search across your application’s users at Transmit. This endpoint also allows you to return all of your application’s users by sending no filters at all. <br><br>**Required permissions**: `users:read`, `users:list`, `apps:read`, `[appId]:read`, `apps:list`, `[appId]:list`.'
parameters:
- name: search
required: false
in: query
description: Search expression based on the [SCIM protocol](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2). For syntax and searchable fields, see [Search query syntax](/openapi/scim_search_syntax/)
schema:
type: string
- name: page_offset
required: false
in: query
description: Number of users you wish to skip before selecting users
schema:
type: number
- name: page_limit
required: false
in: query
description: Number of users to return in page
schema:
maximum: 5000
type: number
- name: search_prefix
required: false
in: query
description: Value to search for in the primary email and phone_number fields, where the search value must match the prefix of the field value. For example, "search_prefix=john" will return users whose email starts with "john" and "search_prefix=%2B1212" returns users whose phone number starts with "+1212".
example: joe
schema:
type: string
- name: sort_field
required: false
in: query
description: 'The name of the field you wish to sort by. Mgmt flows also support: organization_added_at (sort by when member was added to org)'
schema:
default: created_at
enum:
- email
- created_at
- phone_number
- last_auth
- organization_added_at
type: string
- name: sort_order
required: false
in: query
description: The order of the sort
schema:
default: asc
enum:
- asc
- desc
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiGetAllUsers'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/identifier:
get:
operationId: getUserByIdentifier
summary: Get user by identifier
description: 'Search for a user by identifier. <br><br>**Required permissions**: `apps:read`, `[appId]:read`, `users:read`.'
parameters:
- name: identifier_name
required: true
in: query
description: 'Identifier name: one of the built-ins (email, phoneNumber, externalUserId, username, idpIdentifier) or a tenant-defined custom identifier'
schema:
type: string
- name: identifier_value
required: true
in: query
description: Identifier value
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUserByIdentifier
type: object
required:
- result
description: ''
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}:
get:
operationId: getUserById
summary: Get user by ID
description: 'Search for a user by user ID. <br><br>**Required permissions**: `apps:read`, `[appId]:read`, `users:read`.'
parameters:
- name: user_id
required: true
in: path
description: The user ID to search for
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUserById
type: object
required:
- result
description: ''
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
put:
operationId: updateUser
summary: Update user
description: 'Update a user''s attributes or their custom data. Changes will be merged into the user''s profile, so you can specify only the fields you want to update. <br><br> **Note:** <ul> <li> Attributes (like name and address) **cannot** be partially updated, as the new value of an object or array will just replace the current one.</li> <li>`custom_data` **can** be partially updated since it will be merged with the existing data (as a shallow merge).</li></ul>. <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`, `users:edit`.'
parameters:
- name: user_id
required: true
in: path
description: The ID of the user that should be updated
schema:
type: string
- name: user-agent
required: false
in: header
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiUpdateUserInput'
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-updateUser
type: object
required:
- result
description: The user has been successfully updated.
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}/groups:
get:
operationId: getUserGroups
summary: Get user's groups
description: 'Retrieve a list of groups associated with a user. <br><br>**Required permissions**: `apps:read`, `[appId]:read`, `groups:read`.'
parameters:
- name: user_id
required: true
in: path
description: ID of the user to retrieve groups for
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUserGroups
type: object
required:
- result
description: ''
properties:
result:
type: array
items:
$ref: '#/components/schemas/ApiGroup'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/email/{email}:
get:
operationId: getUserByEmail
summary: Get user by email
description: 'Search for a user by primary email. <br><br>**Required permissions**: `apps:read`, `[appId]:read`, `users:read`.'
parameters:
- name: email
required: true
in: path
description: The user's primary email to search for
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUserByEmail
type: object
required:
- result
description: ''
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/external-user-id/{external_user_id}:
get:
operationId: getUserByExternalUserId
summary: Get user by external user ID
description: 'Search for a user by their external_user_id, which represents the user identifier in external provider. <br><br>**Required permissions**: `apps:read`, `[appId]:read`, `users:read`.'
parameters:
- name: external_user_id
required: true
in: path
description: The external user ID to search for
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUserByExternalUserId
type: object
required:
- result
description: ''
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/username/{username}:
get:
operationId: getUserByUsername
summary: Get user by username
description: 'Search for a user by username. <br><br>**Required permissions**: `apps:read`, `[appId]:read`, `users:read`.'
parameters:
- name: username
required: true
in: path
description: The user's username to search for
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUserByUsername
type: object
required:
- result
description: ''
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}/apps:
delete:
operationId: removeUserFromApp
summary: Remove user from app
description: 'Remove a user from the requesting application. <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`, `users:edit`.'
parameters:
- name: user_id
required: true
in: path
description: The ID of the user to remove from application
schema:
type: string
responses:
'204':
description: User removed
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}/password:
post:
operationId: addPasswordCredential
summary: Create credentials
description: 'Creates new password credentials for a user that doesn''t already have a password. The password is temporary, and must be reset upon the user''s first login. <br><br>**Required permissions**: `apps:create`, `[appId]:create`, `authenticators:create`.'
parameters:
- name: user_id
required: true
in: path
description: The ID of the user
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiAddPassword'
responses:
'201':
description: ''
content:
application/json:
schema:
title: ApiCreatedResponse-addPasswordCredential
type: object
required:
- result
description: The password of the user has been successfully added.
properties:
result:
$ref: '#/components/schemas/RegisterPasswordResponse'
'400':
description: Password validation errors
content:
application/json:
schema:
type: object
properties:
error_code:
type: string
enum:
- system_invalid_input
- auth_password_breached
- auth_password_policy_disabled
- auth_password_weak
message:
type: string
'404':
description: User does not exist
content:
application/json:
schema:
type: object
properties:
error_code:
type: string
enum:
- user_not_found
message:
type: string
'409':
description: Password already configured for this user
content:
application/json:
schema:
type: object
properties:
error_code:
type: string
enum:
- auth_password_already_configured
message:
type: string
security:
- ClientAccessToken: []
tags:
- Users
put:
operationId: updatePasswordCredential
summary: Update password
description: 'Updates the user''s existing credentials with a new temporary password, which must be reset the next time they login. <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`, `authenticators:edit`.'
parameters:
- name: user_id
required: true
in: path
description: The ID of the user
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiUpdatePassword'
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-updatePasswordCredential
type: object
required:
- result
description: The password of the user has been successfully added.
properties:
result:
$ref: '#/components/schemas/RegisterPasswordResponse'
'400':
description: Password validation errors
content:
application/json:
schema:
type: object
properties:
error_code:
type: string
enum:
- system_invalid_input
- auth_password_recently_used
- auth_password_breached
- auth_password_policy_disabled
- auth_not_active
- auth_password_incomplete_credentials
- auth_password_weak
message:
type: string
'404':
description: User does not exist
content:
application/json:
schema:
type: object
properties:
error_code:
type: string
enum:
- user_not_found
message:
type: string
'409':
description: Password not configured for this user
content:
application/json:
schema:
type: object
properties:
error_code:
type: string
enum:
- auth_password_already_configured
message:
type: string
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/phone/{phone_number}:
get:
operationId: deprecatedGetUserByPhone
summary: Get user by phone number
description: Search for a user by their primary phone number
deprecated: true
parameters:
- name: phone_number
required: true
in: path
description: The phone number of the user to get
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-deprecatedGetUserByPhone
type: object
required:
- result
description: The requested user result
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/phone-number/{phone_number}:
get:
operationId: getUserByPhone
summary: Get user by phone number
description: 'Search for a user by their primary phone number. <br><br>**Required permissions**: `apps:read`, `[appId]:read`, `users:read`.'
parameters:
- name: phone_number
required: true
in: path
description: The phone number of the user to get
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getUserByPhone
type: object
required:
- result
description: The requested user result
properties:
result:
$ref: '#/components/schemas/ApiUser'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestHttpError'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}/emails/{email}:
delete:
operationId: removeUserSecondaryEmail
summary: Remove secondary email
description: 'Removes a secondary email address from the user''s profile. <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`, `users:edit`.'
parameters:
- name: email
required: true
in: path
description: Secondary email to remove
schema:
type: string
- name: user_id
required: true
in: path
description: ID of the user
schema:
type: string
responses:
'204':
description: Secondary email is removed
'400':
description: ''
'404':
description: ''
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}/phone-numbers/{phone_number}:
delete:
operationId: removeUserSecondaryPhoneNumber
summary: Remove secondary phone number
description: 'Remove a secondary phone number from the user''s profile. <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`, `users:edit`.'
parameters:
- name: phone_number
required: true
in: path
description: Secondary phone number to remove
schema:
type: string
- name: user_id
required: true
in: path
description: ID of the user
schema:
type: string
responses:
'204':
description: Secondary phone number is removed
'400':
description: ''
'404':
description: ''
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}/emails/{email}/verify:
post:
operationId: verifyUserEmail
summary: Mark email as verified
description: 'Indicates that the user''s email address was verified externally. A user''s email address is automatically marked as verified when used in a Transmit authentication or verification flow. If the email address is a secondary email, the request can also be used to set it as the user''s primary email (by setting `change_to_primary` to `true`). <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`, `users:edit`.'
parameters:
- name: user_id
required: true
in: path
description: The ID of the user that should be updated
schema:
type: string
- name: email
required: true
in: path
description: The email of the user that should be verified
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserVerifyEmailOrPhoneNumberInput'
responses:
'202':
description: User email has been verified
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/{user_id}/phone-numbers/{phone_number}/verify:
post:
operationId: verifyUserPhoneNumber
summary: Mark phone as verified
description: 'Indicates that the user''s phone number was verified externally. A user''s phone number is automatically marked as verified when used in a Transmit authentication or verification flow. If the phone number is a secondary one, the request can also be used to set it as the user''s primary phone (by setting `change_to_primary` to `true`). <br><br>**Required permissions**: `apps:edit`, `[appId]:edit`, `users:edit`.'
parameters:
- name: phone_number
required: true
in: path
description: The phone number of the user that should be verified
schema:
type: string
- name: user_id
required: true
in: path
description: The ID of the user that should be updated
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserVerifyEmailOrPhoneNumberInput'
responses:
'202':
description: User phone number has been verified
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- ClientAccessToken: []
tags:
- Users
/v1/users/me/password-credentials:
post:
operationId: addPasswordCredentialsToCurrentUser
summary: Register password
description: Allows a logged-in user to register their first password. Must be authorized using a valid user access token returned upon successful authentication.
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiMeAddPassword'
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-addPasswordCredentialsToCurrentUser
type: object
required:
- result
description: Password registered
properties:
result:
$ref: '#/components/schemas/RegisterPasswordResponse'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenHttpError'
security:
- UserAccessToken: []
tags:
- Users
/v1/users/me/device-keys:
get:
operationId: getDeviceKeysForTenant
summary: Get current user's device keys
description: Get device keys by user id
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
title: ApiOkResponse-getDeviceKeysForTenant
type: object
required:
- result
description: User's device keys information
properties:
result:
$ref: '#/components/schemas/DeviceKeyResponseDto'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundHttpError'
security:
- UserAccessToken: []
tags:
- Users
components:
schemas:
ApiUserIdentity:
type: object
properties:
provider_name:
type: string
description: Name of identity provider
provider_type:
type: string
description: Indicates whether the identity provider is Transmit (Native) or a social login provider (OAuth2)
enum:
- OAuth2
- Native
- External
auth_type:
type: string
enum:
- webauthn
- email_otp
- sms_otp
- direct_otp
- email_magic_link
- password
- oauth2
- saml
- transmit
- totp
description: Type of authentication method that was used
identifier:
type: string
description: Identifier of the user in the provider's system
user_alias:
description: Alias used by the user to authenticate to this provider
allOf:
- $ref: '#/components/schemas/ApiUserIdentityAlias'
first_auth_date:
format: date-time
type: string
description: Date user first authenticated to this provider
last_auth_date:
format: date-time
type: string
description: Date user last authenticated to this provider
required:
- provider_name
- provider_type
- auth_type
- identifier
- first_auth_date
- last_auth_date
ApiUserPasswordInput:
type: object
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/transmit-security/refs/heads/main/openapi/transmit-security-users-api-openapi.yml