Skip to content
shiftagent Integration API

Look up a user by external ID.

GET
/tenants/{tenant_id}/users/by-external-id/{external_id}
 
curl --request GET \
  --url https://shiftagent.example.com/tenants/example/users/by-external-id/example \
  --header 'Authorization: Bearer <token>'

Pure lookup by the host system’s user ID within the tenant — never creates. 404 not-found if absent.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
tenant_id
required
string
/^tnt_[A-Za-z0-9]+$/

Internal tenant ID.

external_id
required
string
>= 1 characters <= 255 characters

The host system’s identifier, namespaced by the adapter (e.g. {ns}:tenant:{id} / {ns}:user:{id}). Opaque to shiftagent — compared byte-exact after trimming; case-sensitive; URL-encode reserved characters (: → %3A where required by the client).

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The user.

Media type application/json

A host-system end user within one tenant. Effective skills = union over assigned roles of each role’s resolved skills.

object
object
required
string
Allowed value: user
id
required
string
/^usr_[A-Za-z0-9]+$/
tenant_id
required
string
/^tnt_[A-Za-z0-9]+$/
external_id
required

Host system’s user ID (namespaced by the adapter). Unique per tenant; natural key for upsertUserByExternalId.

string
<= 255 characters
email
required

Optional profile field — enrichable after creation.

string | null format: email
display_name
required

Optional profile field — enrichable after creation.

string | null
<= 255 characters
status
required

suspended (deactivated) users fail token exchange and cannot start conversations; they are never auto re-provisioned by upsert.

string
Allowed values: active suspended
role_ids
required

Assigned roles (also manageable via assignUserRole).

Array<string>
default_repository_id
required

Per-user repository override in the resolution cascade.

string | null
/^rep_[A-Za-z0-9]+$/
storage
required

S3-style storage bucket attached to a user or conversation. Platform-assigned automatically at creation; host-owned buckets can be linked via update (provider: "external").

object
provider
required

platform — bucket provisioned and owned by the deployment; external — host-linked BYO bucket.

string
Allowed values: platform external
bucket_uri
required

S3-style URI of the bucket root (e.g. s3://bucket/prefix).

string
metadata
required

Free-form string key–value map for host/adapter bookkeeping (e.g. a host-side reference ID). Max 50 keys; values max 500 chars. Replaced wholesale when provided in updates.

object
<= 50 properties
key
additional properties
string
<= 500 characters
created_at
required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time
updated_at
required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time
Example 
{
  "object": "user",
  "status": "active",
  "storage": {
    "provider": "platform"
  }
}

401

Section titled “401 ”

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples
Example unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}

404

Section titled “404 ”

Not found — the resource does not exist, was deprovisioned, or lies outside the integration key’s subtree (indistinguishable by design).

Media type application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object
type
required

Problem type URI (registry slug).

string format: uri-reference
title
required

Short, human-readable summary of the problem type.

string
status
required

HTTP status code.

integer format: int32
detail

Human-readable explanation specific to this occurrence.

string
instance

URI reference identifying this occurrence.

string format: uri-reference
request_id

Correlation ID for support and log lookup.

string
conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string
errors

On validation-error, field-level details.

Array<object>
object
pointer
required

JSON pointer to the offending field.

string
message
required

What failed.

string
Examples
Example not_found

Unknown resource

{
  "type": "https://shiftagent.example.com/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No tenant with external_id acme:tenant:999999.",
  "request_id": "req_01hzx8nf001"
}