Breadcrumbs

User API

Use the Yarken User API to programmatically manage users and their access to Yarken. You can integrate the API with identity management platforms, integration tools, scripts, or custom applications to automate supported user lifecycle activities.

About this page: Use this page for User API concepts, authentication, common request behavior, and user-management rules. The User API reference provides the complete endpoint definitions, parameters, schemas, and responses.

What you can do

  • List users.

  • Create a user and set their initial access status.

  • Retrieve a user by ID.

  • Update supported user attributes.

  • Disable a user's access without deleting their user record.

  • Re-enable a disabled user.

Before you begin

Access requirement: Only users with the Admin role can access the User API. Other Yarken roles cannot use the API.

Before using the User API:

  • You must have the Admin role. Other roles cannot use the User API.

  • Identify the host name of your Yarken environment.

  • Generate an API key for your integration.

  • Store the API key securely.

  • Use the published /api/v1/ endpoints for new integrations.

For API key setup and security guidance, see API Keys.

User API base path

Use the following base path when constructing User API requests:

https://<YOUR-YARKEN-HOST>/api/v1/users

Replace <YOUR-YARKEN-HOST> with the host name of your Yarken environment.

Note: The User API base path is not an interactive documentation page. API endpoints require authentication and are intended to be called from an integration, script, API client, or the interactive API documentation.

Authenticate requests

Include a valid API key with each User API request.

Use the x-token header:

x-token: <YOUR_API_KEY>

You can alternatively use the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

You only need one authentication method for a request.

Important: Treat API keys as sensitive credentials. Do not include API keys in documentation, tickets, emails, screenshots, or other unsecured locations.

Unauthorized response

If the API key is missing or invalid, Yarken returns HTTP status 401:

JSON
{
  "error": "Unauthorized: Invalid or missing API key"
}

API quick reference

Action

Method

Endpoint

List users

GET

/api/v1/users

Create a user

POST

/api/v1/users

Get a user by ID

GET

/api/v1/users/{id}

Update a user

PATCH

/api/v1/users/{id}

Disable a user

POST

/api/v1/users/disable

Important: For retrieve and update operations, {id} is the user's UUID. Do not use the user's email address in the path.

Note: The disable operation identifies the user by the email address provided in the JSON request body.

List users

GET /api/v1/users returns a paginated list of users. Internal user fields are not returned.

You can use the following optional query parameters:

Parameter

Rules

page

Integer greater than or equal to 1. Default: 1.

pageSize

Integer from 1 to 100. Default: 50.

disabled

Use the query value true or false.

email

Exact email match. Matching is case-insensitive.

Results are ordered by user name in ascending order.

User identifiers

Yarken returns a stable UUID in the id field for each user.

Use this ID with:

  • GET /api/v1/users/{id}

  • PATCH /api/v1/users/{id}

Create and update user data

When creating or updating a user, Yarken supports the following fields:

Field

Type

Behavior

name

string

Trimmed. Must contain 1–255 characters.

username

string

Trimmed. Must contain 1–255 characters.

email

string

Must be a valid email address. Maximum 255 characters. Yarken stores the value in lowercase when written through the API.

roles

string[] or string

Provide one or more supported role codes.

disabled

boolean

Controls whether the user can access Yarken.

Create a user

For POST /api/v1/users, name, username, and email are required.

  • If roles is omitted, Yarken assigns norole.

  • If disabled is omitted, Yarken sets it to false.

  • A successful request returns HTTP status 201 and a Location header for the new user resource.

Update a user

PATCH /api/v1/users/{id} performs a partial update. Provide only the fields you want to change.

  • Provide at least one supported field.

  • Unknown JSON fields are rejected.

  • An empty request body returns HTTP status 422.

Supported role values

Role codes are case-sensitive.

Role assignment: The values below are roles an Admin can assign to users through the API. They do not determine who can use the API. Only users with the Admin role can access the User API.

Yarken role

API role code

No role

norole

Admin

admin

Power User

powerUser

Viewer

viewer

Dashboard Only

dashboardOnly

Budget Process Owner

budgetProcessOwner

Budget Contributor

budgetContributor

Chargeback Approver

chargebackApprover

Cloud Engineer

cloudEngineer

Cloud Cost Owner

cloudCostOwner

Cost Model Manager

costModelManager

Important: You cannot assign the userAdmin role through the User API.

You can provide roles as a JSON array:

JSON
{
  "roles": ["viewer", "budgetContributor"]
}

You can also provide a comma-separated string. Duplicate role values are removed.

Disable and re-enable users

Use POST /api/v1/users/disable to disable a user by email address:

JSON
{
  "email": "user@example.com"
}

The operation sets disabled to true and does not delete the user record. Repeating the operation for an already disabled user is safe and still returns HTTP status 200 with the user.

To re-enable a user, update the user by UUID and set:

JSON
{
  "disabled": false
}

Common response codes

Status

Description

200

The request completed successfully.

201

The user was created successfully.

401

The API key is missing or invalid.

404

The requested user was not found.

409

The email address or username conflicts with an existing user.

422

The request failed validation.

Test API requests

Use the interactive API documentation in your Yarken environment to review and test User API requests:

https://<YOUR-YARKEN-HOST>/api/docs

  1. Open /api/docs from your Yarken environment.

  2. Click Authorize.

  3. Enter your API key using either ApiKeyAuth or BearerAuth. You only need one.

  4. Open the required User API endpoint.

  5. Click Try it out, enter the required values, and click Execute.

  6. Review the generated request and server response.

Important: POST and PATCH requests can change data in the Yarken environment. Use the interactive documentation only when you intend to create, update, disable, or re-enable a user.

Note: The Help Center API reference is intended for browsing the published API contract. Run interactive requests from your Yarken-hosted /api/docs page.

Related content