---
title: "Register an external user"
method: POST
path: "/external-users"
tags: ["External Users"]
---

# Register an external user

`POST /external-users`

## Request

- Base URL: `https://openrouter.ai/api/v1`
- URL: `https://openrouter.ai/api/v1/external-users`
- Auth: HTTP bearer

Register a caller-supplied tracking ID under the authenticated organization. No login account, policy, or credentials are created. [Management key](/docs/guides/overview/auth/management-api-keys) required.

## Request body

- CreateExternalUserRequest
  - `user` string, required: Immutable case-sensitive tracking string supplied as user on inference requests or as external.user on API keys: 1 to 512 characters, well-formed Unicode, no NUL, no surrounding whitespace. URL-encode it in resource paths; an ID of `.` or `..` cannot be addressed by path, so look it up with the list filter.

## Response `201`

The registered external user. No generated public identifier is returned.

- ExternalUserResponse
  - `data` ExternalUser, required
    - `created_at` string, date-time, required: Registration creation time.
    - `is_active` boolean, required: Whether this registration is active. Not an inference authorization decision.
    - `updated_at` string, date-time, required: Last registration lifecycle update time.
    - `user` string, required: Immutable case-sensitive tracking string supplied as user on inference requests or as external.user on API keys: 1 to 512 characters, well-formed Unicode, no NUL, no surrounding whitespace. URL-encode it in resource paths; an ID of `.` or `..` cannot be addressed by path, so look it up with the list filter.

## Other responses

- `400`: Bad Request - Invalid request parameters or malformed input
- `401`: Unauthorized - Authentication required or invalid credentials
- `404`: Not Found - Resource does not exist
- `409`: The tracking ID is already registered in this organization, active or not.
- `500`: Internal Server Error - Unexpected server error

## Changes

- **2026-10-21** `e51bb1f02f3e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/external-users/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) - [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/d6f0173bb1c8?raw)