GET `/users/{userId}`

Get user by ID

Returns a single unified user by ID. The ID may be given in any supported style: the unified user ID (UUID) or a native infrastructure user ID (currently Alianza One — Base62-URL or legacy numeric; Core/Fusion styles will resolve once those infrastructures are supported, and return 404 until then). The returned user always carries the unified ID.

A user the caller is not authorized to view is reported as 404, identically to a user that does not exist, so that this endpoint cannot be used to discover which user IDs are real.

Authentication

OAuth 2.0. Required scope(s): users:manage.

Request

Path parameters

Name	Type	Required	Description
`userId`	string	yes	The user ID in any supported style (unified UUID or native One ID). Unsupported styles return 404.

Query parameters

None.

Headers

None.

Responses

`200` — User retrieved successfully.

Content-Type: application/json

Schema: UnifiedUser

Field	Type	Required	Description
`id`	string (uuid), read-only	yes	Unique unified user identifier.
`accountId`	string (uuid), read-only	yes	The unified account this user belongs to.
`firstName`	string	no	User's first name.
`lastName`	string	no	User's last name.
`createdAt`	string (date-time), read-only	yes	When the entity was created. ISO 8601 UTC format.
`updatedAt`	string or null (date-time), read-only	no	When the entity was last updated. ISO 8601 UTC format. Null if never updated.

Example:

{
  "id": "f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Jane",
  "lastName": "Doe",
  "createdAt": "2026-03-15T14:22:00.000000Z",
  "updatedAt": "2026-03-18T09:15:30.000000Z"
}

`401` — Unauthorized

The OAuth token is missing, invalid, or carries no urn:alianza:claims:principal_id claim. Authentication is required via bearer token.

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "type": "https://problems-registry.smartbear.com/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing or invalid bearer token.",
  "instance": "/users/f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`403` — Forbidden - The access token does not hold the `users:manage` scope. A caller that holds the scope but may not view this user receives a 404, not a 403

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "type": "https://problems-registry.smartbear.com/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The caller is not permitted to perform this operation.",
  "instance": "/users/f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`404` — No user found with the given ID, the caller is not authorized to view it, or the ID is not in a supported format

These cases are deliberately indistinguishable, so that the endpoint cannot be used to discover which user IDs exist.

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "type": "https://problems-registry.smartbear.com/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "User not found with id=f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "instance": "/users/f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`429` — Too many requests. The client has exceeded the rate limit for this API.

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please slow down and try again.",
  "instance": "/users/f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`500` — Unexpected server error. `detail` is always this fixed generic message.

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "type": "https://problems-registry.smartbear.com/server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request.",
  "instance": "/users/f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

`503` — Service temporarily unavailable, including when the authorization service cannot be reached, which fails closed

Content-Type: application/problem+json

Schema: ProblemDetails

Example:

{
  "type": "https://problems-registry.smartbear.com/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The service is temporarily unavailable. Please try again later.",
  "instance": "/users/f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
  "traceId": "6d4a3a62-0d4b-4b96-9171-8c5070e01c35"
}

Errors

This operation may return:

401 — Unauthorized - The OAuth token is missing, invalid, or carries no urn:alianza:claims:principal_id claim
403 — Forbidden - The access token does not hold the users:manage scope
404 — No user found with the given ID, the caller is not authorized to view it, or the ID is not in a supported format
429 — Too many requests. The client has exceeded the rate limit for this API.
500 — Unexpected server error. detail is always this fixed generic message.
503 — Service temporarily unavailable, including when the authorization service cannot be reached, which fails closed

See Errors reference for the full catalogue.

Schema: UnifiedUser
Schema: ProblemDetails