Texada User Management API: Technical Documentation

In This Article

• Introduction
• Purpose of the Document
• Consuming APIs
• Token API Service
  • Introduction
  • Authentication
  • Endpoints
    • Sign Token
      • Request Headers
      • Request Body
      • Responses
• User Management API Service
  • Introduction
  • Authentication
  • Response Codes
  • Endpoints
    • Get a User
      • Path Parameters
      • Responses
    • Create a User
      • Request Body
      • Responses
    • Update a User
      • Path Parameters
      • Request Body
      • Responses

Introduction

Texada’s User Management APIs are the first externally-exposed Texada platform APIs, empowering customers to self-manage their users. This critical functionality will both allow customers to create users programmatically and enable them to migrate and change their domains through a self-serve model.

Purpose of the Document

This document will provide the steps required to acquire and apply Access Tokens, which are required to use for all APIs, as well as the available API URLs per environment. After reading this document, you should be able to authenticate your calls and call any API.

Consuming APIs

In order to start consuming the APIs, you will need:

1. Valid API Keys provided by Texada.
2. An access URL. This will change depending on your organization’s region:
   • North America: https://use.api.texadasoftware.com
   • Europe: https://euc.api.texadasoftware.com
   • APAC: https://au.api.texadasoftware.com
3. An Access Token signed using the provided API Key.

Once acquired, the API Key and Access Token will need to be passed with each API call.

Token API Service

Introduction

This section provides a comprehensive overview of the Token API Service, including its endpoints, request/response formats, and authentication mechanisms. This API is designed to facilitate the signing of JWT (JSON Web Token) access tokens for user identities within the system.

Authentication

All requests to this service require authentication using a valid API Key.

A valid API Key must be provided in the x-api-key HTTP header for all requests. Failure to provide a valid Key will result in a 401 Unauthorized or 403 Forbidden error.

Endpoints

Sign Token

This endpoint is used to sign a JWT token on behalf of a user identity. The generated token is short-lived and includes user identity, tenant/environment information, and specified scopes.

• Path: /core/token/sign
• Method: POST

Request Headers

Name	In	Required	Type	Description
x-api-key	header	true	string	Unauthorized: Missing x-api-key header!

Request Body

The request body should be in application/json format.

Property	Type	Required	Description
scope	array of strings	true	List of scopes to include in the token. At least one scope is required. Only scopes that belong to the key are allowed.

Example Request cURL:

curl --location 'https://use.api.texadasoftware.com/core/token/sign' \

--header 'x-api-key: my_api_Key' \

--header 'Content-Type: application/json' \

--data '{

    "scope": [

        "core:authorization:create:user",

        "core:authorization:update:user",

        "core:authorization:get:user"

    ]

}'

Responses

200 OK

• Description: Sign JWT token on behalf of user identity. Token is short-lived and includes user identity, tenant information, and scopes.
• Content Type: application/json

Property	Type	Required	Description
token	string	true	The generated JWT token

Example 200 Response:

{

  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyMTIzLWFiYyIsInNjb3BlcyI6WyJyZWFkIiwid3JpdGUiXX0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

}

401 Unauthorized

• Description: Authorization Error.
• Content Type: application/json

Property	Type	Required	Description	Example
message	string	true	Error message	Invalid API Key provided!

Example 401 Response:

{

  "message": "Unauthorized: Missing x-api-key header!"

}

403 Forbidden

• Description: Forbidden Error. This typically occurs when the provided API key does not have the necessary permissions for the requested scopes.
• Content Type: application/json

Property	Type	Required	Description	Example
message	string	true	Error message	Invalid API Key provided!
availableScopes	array of strings	false	List of scopes available for the provided API key.	["read", "write"]
requestedScope	array of strings	false	List of scopes that were requested in the API call.	["read", "write", "admin"]

Example 403 Response:

{

  "message": "Forbidden: One or more requested scopes are not allowed for this API key.",

  "availableScopes": ["read", "write"],

  "requestedScope": ["read", "write", "admin"]

}

User Management API Service

Introduction

This section provides a comprehensive overview of the User Management API Service, including its endpoints, request/response formats, and authentication mechanisms. This API is designed to facilitate user management transactions, specifically focusing on user creation, updates, and retrieval.

Authentication

All requests to this service require authentication using a valid Access Token.

• Security: A valid JWT Access token must be provided in the authorization HTTP header for all requests.
• Scopes: The following scopes are available for the service. Remember, they must be requested during signing the token:
  • core:authorization:create:user
  • core:authorization:update:user
  • core:authorization:get:user

Response Codes

This section outlines common HTTP status codes you may encounter when interacting with the service.

Status	Description
200	Success
401	Unauthorized - the authorization header was missing
403	Forbidden - the authorization header used was invalid
404	Not Found - check that the parameters were correct
500	Internal Server Error

Endpoints

Get a User

This endpoint is used to get a user by email or userId.

• Path: /core/authorization/user/{userIdOrEmail}
• Method: GET
• Scope: core:authorization:get:user

Path Parameters

Name	Type	Required	Format	Examples	Description
userIdOrEmail	string	true	email or uuid	someone@example.com b34d4868-b453-4921-9553-a8085c36ff24	A user identifier, which can be either a valid email address or a UUID.

Responses

200 OK

• Description: Success. Response schema for retrieving a user by email or userId.
• Content Type: application/json

Property	Type	Required	Format	Example	Description
Email	string	true	email	user@email.com	Email associated with a user.
Status	string	true	enum	Active	User status.
FamilyName	string	true	-	Doe	User's family name.
GivenName	string	true	-	John	User's given name.
UserId	string	true	uuid	b34d4868-b453-4921-9553-a8085c36ff24	Unique user identifier.

400 Bad Request

• Description: Input Validation Error.
• Content Type: application/json

Property	Type	Required	Example
success	boolean	true	false
error	object	true	Contains issues (array of objects) and name (Error)

401 Unauthorized

• Description: Authorization Error.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	401
Message	string	true	Invalid API Key provided

404 Not Found

• Description: Could not find a User for the specified Email or UserId.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	404
Message	string	true	Could not find UserEmailHeader for specified Email or UserId: <userIdOrEmail>

500 Internal Server Error

• Description: Internal Server Error.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	500
Message	string	true	Internal Server Error

Create a User

This endpoint is used to create a user. If the tenant is configured to use Username/Password (not using IdP), this API will trigger 2 automated emails: the first to verify the email and the second to set their password.

• Path: /core/authorization/user
• Method: POST
• Scope: core:authorization:create:user

Request Body

The request body should be in application/json format.

Property	Type	Required	Description	Example	Default Value
Email	string	true	Email associated with a user	user@email.com	-
Status	string	false	User status (Active or Inactive)	Active	Active
FamilyName	string	true	User's family name (last name)	Doe	-
GivenName	string	true	User's given name (first name)	John	-
UserMetadata	object	false	Metadata attached to user. Requires UseMFA boolean.	{ "UseMFA": true }	-

Responses

200 OK

• Description: Success.
• Content Type: application/json

Property	Type	Required	Format	Example
UserId	string	true	uuid	b34d4868-b453-4921-9553-a8085c36ff24

400 Bad Request

• Description: Input Validation Error.
• Content Type: application/json

Property	Type	Required	Example
success	boolean	true	false
error	object	true	Contains issues (array of objects) and name (Error)

401 Unauthorized

• Description: Authorization Error.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	401
Message	string	true	Invalid API Key provided

403 Forbidden

• Description: Forbidden.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	403
Message	string	true	Forbidden. User is not authorized to access this route.

500 Internal Server Error

• Description: Internal Server Error.
• Content Type: application/json

Property	Type	Required	Example
errors	array of objects	true	Array of error objects (StatusCode, Message, source)
UserId	string	true	b34d4868-b453-4921-9553-a8085c36ff24

Update a User

This endpoint is used to update a user. If the tenant is configured to use Username/Password (not using IdP), this API will trigger an invitation email to the new user to validate the email if the email has been changed.

Updates information associated with an external user without mandatory tenant/environment consistency checks. This API allows changing users across tenants and environments. Changing a user’s status to Inactive will cause all environments and tenants to be unassigned from that user.

• Path: /core/authorization/user/{userIdOrEmail}
• Method: PATCH
• Scope: core:authorization:update:user

Path Parameters

Name	Type	Required	Format	Examples	Description
userIdOrEmail	string	true	email or uuid	someone@example.com b34d4868-b453-4921-9553-a8085c36ff24	A user identifier, which can be either a valid email address or a UUID.

Request Body

The request body should be in application/json format.

Property	Type	Required	Description	Example
Email	string	false	Email associated with a user	user@email.com
Status	string	false	User status (Active or Inactive)	Active
FamilyName	string	false	User's family name (last name)	Doe
GivenName	string	false	User's given name (first name)	John
UserMetadata	object	false	Metadata attached to user. Requires UseMFA boolean.	{ "UseMFA": true }

Responses

200 OK

• Description: Success.
• Content Type: application/json

Property	Type	Required
Message	string	true

400 Bad Request

• Description: Input Validation Error.
• Content Type: application/json

Property	Type	Required	Example
success	boolean	true	false
error	object	true	Contains issues (array of objects) and name (Error)

401 Unauthorized

• Description: Authorization Error.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	401
Message	string	true	Invalid API Key provided

404 Not Found

• Description: Could not find User Email Header for specified Email.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	404
Message	string	true	Could not find UserEmailHeader for specified Email: <email>

409 Conflict

• Description: Record already exists.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	409
Message	string	true	Record already exists

500 Internal Server Error

• Description: Internal Server Error.
• Content Type: application/json

Property	Type	Required	Example
StatusCode	number	true	500
Message	string	true	Internal Server Error