The User API reference provides the published endpoints, parameters, request bodies, response schemas, and HTTP status codes for the Yarken User API.
OpenAPI specification: Yarken publishes the User API contract using OpenAPI 3.0.3. The current machine-readable specification is available from your Yarken environment at https://<YOUR-YARKEN-HOST>/api/openapi.json.
Access requirement: Only users with the Admin role can use the Yarken User API. Other Yarken roles cannot execute User API operations.
OpenAPI reference
Use the OpenAPI reference below to review endpoint definitions, request parameters, request bodies, response schemas, and documented HTTP responses.
JSON
{
"openapi": "3.0.3",
"info": {
"title": "Yarken Public API (v1)",
"version": "1.0.0",
"description": "External integration APIs authenticated with a tenant API key.\n\n## Authentication\nCreate a key in **App Settings → API Keys**. Send it on every request using either:\n\n- Header `x-token: <YOUR_API_KEY>`\n- Header `Authorization: Bearer <YOUR_API_KEY>`\n\nA missing or invalid key returns `401` with `{ \"error\": \"Unauthorized: Invalid or missing API key\" }`."
},
"servers": [{ "url": "/api", "description": "This host" }],
"security": [{ "ApiKeyAuth": [] }, { "BearerAuth": [] }],
"tags": [
{
"name": "Users",
"description": "Public user administration. Read/update by UUID in the path; disable by email in the JSON body."
}
],
"paths": {
"/v1/users": {
"get": {
"tags": ["Users"],
"summary": "List users",
"operationId": "v1UsersList",
"parameters": [
{
"name": "page",
"in": "query",
"schema": { "type": "integer", "minimum": 1, "default": 1 }
},
{
"name": "pageSize",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 50
}
},
{
"name": "disabled",
"in": "query",
"schema": { "type": "string", "enum": ["true", "false"] }
},
{
"name": "email",
"in": "query",
"schema": { "type": "string", "format": "email" },
"description": "Exact email match (case-insensitive)."
}
],
"responses": {
"200": {
"description": "Paginated users. Internal fields are never returned.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/UserList" }
}
}
},
"401": {
"description": "Missing or invalid API key",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/UnauthorizedError" }
}
}
},
"422": {
"description": "Request failed schema validation",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ResultMessage" }
}
}
}
}
},
"post": {
"tags": ["Users"],
"summary": "Create a user",
"operationId": "v1UsersCreate",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": ["name", "username", "email"],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"username": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"roles": {
"description": "One or more public roles. `userAdmin` cannot be assigned via this API.",
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"norole",
"admin",
"powerUser",
"viewer",
"dashboardOnly",
"budgetProcessOwner",
"budgetContributor",
"chargebackApprover",
"cloudEngineer",
"cloudCostOwner",
"costModelManager"
]
},
"minItems": 1
},
{
"type": "string",
"description": "Comma-separated role codes."
}
]
},
"disabled": { "type": "boolean", "default": false }
}
}
}
}
},
"responses": {
"201": {
"description": "Created user. `Location` is `/api/v1/users/{id}`.",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/User" }
}
}
},
"401": {
"description": "Missing or invalid API key",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/UnauthorizedError" }
}
}
},
"409": {
"description": "Email or username already exists",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": { "type": "string", "example": "Conflict" },
"message": { "type": "string" }
}
}
}
}
},
"422": {
"description": "Request failed schema validation",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ResultMessage" }
}
}
}
}
}
},
"/v1/users/{id}": {
"get": {
"tags": ["Users"],
"summary": "Get a user by id",
"operationId": "v1UsersGet",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": { "type": "string", "format": "uuid" },
"description": "Stable user id. Do not put email in the path."
}
],
"responses": {
"200": {
"description": "User",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/User" }
}
}
},
"401": {
"description": "Missing or invalid API key",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/UnauthorizedError" }
}
}
},
"404": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": { "type": "string", "example": "User not found" }
}
}
}
}
},
"422": {
"description": "Request failed schema validation",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ResultMessage" }
}
}
}
}
},
"patch": {
"tags": ["Users"],
"summary": "Update a user",
"description": "Partial update. Only provided fields are changed. Unknown body keys are rejected.",
"operationId": "v1UsersUpdate",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": { "type": "string", "format": "uuid" },
"description": "Stable user id. Do not put email in the path."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"username": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"roles": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"norole",
"admin",
"powerUser",
"viewer",
"dashboardOnly",
"budgetProcessOwner",
"budgetContributor",
"chargebackApprover",
"cloudEngineer",
"cloudCostOwner",
"costModelManager"
]
},
"minItems": 1
},
{ "type": "string" }
]
},
"disabled": { "type": "boolean" }
}
}
}
}
},
"responses": {
"200": {
"description": "Updated user",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/User" }
}
}
},
"401": {
"description": "Missing or invalid API key",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/UnauthorizedError" }
}
}
},
"404": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": { "type": "string", "example": "User not found" }
}
}
}
}
},
"409": {
"description": "Email or username already exists",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": { "type": "string", "example": "Conflict" },
"message": { "type": "string" }
}
}
}
}
},
"422": {
"description": "Request failed schema validation",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ResultMessage" }
}
}
}
}
}
},
"/v1/users/disable": {
"post": {
"tags": ["Users"],
"summary": "Disable a user by email",
"description": "Looks up the user by `email` in the JSON body (not the URL). Sets `disabled` to true. The record is not deleted. Idempotent if already disabled.",
"operationId": "v1UsersDisable",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": ["email"],
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 255
}
}
}
}
}
},
"responses": {
"200": {
"description": "Disabled user",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/User" }
}
}
},
"401": {
"description": "Missing or invalid API key",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/UnauthorizedError" }
}
}
},
"404": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": { "type": "string", "example": "User not found" }
}
}
}
}
},
"422": {
"description": "Request failed schema validation",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ResultMessage" }
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-token",
"description": "Tenant API key (raw key from App Settings, not the stored hash)."
},
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Same tenant API key as `x-token`, sent as `Authorization: Bearer <key>`."
}
},
"schemas": {
"UnauthorizedError": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Unauthorized: Invalid or missing API key"
}
}
},
"ResultMessage": {
"type": "object",
"properties": {
"result": { "type": "boolean" },
"message": { "type": "string" }
}
},
"User": {
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"name": { "type": "string" },
"username": { "type": "string" },
"email": { "type": "string", "format": "email" },
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"norole",
"admin",
"powerUser",
"viewer",
"dashboardOnly",
"budgetProcessOwner",
"budgetContributor",
"chargebackApprover",
"cloudEngineer",
"cloudCostOwner",
"costModelManager"
]
}
},
"disabled": { "type": "boolean" },
"createdAt": { "type": "string", "format": "date-time" },
"updatedAt": { "type": "string", "format": "date-time" }
}
},
"UserList": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": { "$ref": "#/components/schemas/User" }
},
"page": { "type": "integer", "minimum": 1 },
"pageSize": { "type": "integer", "minimum": 1, "maximum": 100 },
"total": { "type": "integer", "minimum": 0 }
}
}
}
}
}
Interactive requests: Use this Confluence reference to browse the API contract. To authorize and execute API requests, use the Yarken-hosted interactive documentation at https://<YOUR-YARKEN-HOST>/api/docs.
Interactive API documentation
To test API requests from your Yarken environment, open:
https://<YOUR-YARKEN-HOST>/api/docs
From the interactive documentation, you can authorize with your API key, select an endpoint, provide request values, execute the request, and review the server response.
Important: Requests executed from the Yarken-hosted /api/docs page can change data. Use POST and PATCH operations only when you intend to create, update, disable, or re-enable a user.