Search Documentation
Search across all documentation pages
Users

The User object

A user represents an authenticated person on the platform. Users are provisioned automatically on first login via WorkOS and belong to one or more organizations through memberships.

Base path: transcodely.v1.UserService

Attributes

AttributeTypeDescription
idstringUnique identifier. Prefixed with usr_.
emailstringEmail address.
email_verifiedbooleanWhether the email has been verified.
first_namestringFirst name.
last_namestringLast name.
profile_picture_urlstringURL to profile picture. Omitted if not set.
statusstringOne of: active, suspended, deleted.
last_login_atstringISO 8601 timestamp of last login. Omitted if never logged in.
created_atstringISO 8601 timestamp.
updated_atstringISO 8601 timestamp.
{
  "id": "usr_a1b2c3d4e5",
  "email": "jane@acme.com",
  "email_verified": true,
  "first_name": "Jane",
  "last_name": "Doe",
  "profile_picture_url": "https://cdn.example.com/avatars/jane.jpg",
  "status": "active",
  "last_login_at": "2025-02-28T09:15:00Z",
  "created_at": "2025-01-10T08:00:00Z",
  "updated_at": "2025-02-28T09:15:00Z"
}

Retrieve current user

Retrieve the authenticated user’s profile and their organization memberships.

Does not require X-Organization-ID header.

POST /transcodely.v1.UserService/GetMe

Parameters

No parameters. The user is identified from the authentication context.

Returns

Returns a UserWithOrganizations object containing the user profile and a list of organizations the user belongs to.

FieldTypeDescription
userUserThe User object.
organizationsUserOrganization[]Organizations the user belongs to.

UserOrganization

FieldTypeDescription
org_idstringOrganization ID.
org_slugstringOrganization slug.
org_namestringOrganization display name.
rolestringUser’s role: owner, admin, member, or viewer.
is_activebooleanWhether this membership is active.
curl -X POST https://api.transcodely.com/transcodely.v1.UserService/GetMe 
  -H "Authorization: Bearer ak_live_abc123" 
  -H "Content-Type: application/json" 
  -d '{}'
{
  "user": {
    "user": {
      "id": "usr_a1b2c3d4e5",
      "email": "jane@acme.com",
      "email_verified": true,
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "active",
      "last_login_at": "2025-02-28T09:15:00Z",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-02-28T09:15:00Z"
    },
    "organizations": [
      {
        "org_id": "org_f6g7h8i9j0",
        "org_slug": "acme-corp",
        "org_name": "Acme Corporation",
        "role": "owner",
        "is_active": true
      }
    ]
  }
}

Retrieve a user

Retrieve a user by ID. Requires admin permission on the organization, or the authenticated user must be requesting their own profile.

Requires: X-Organization-ID header.

POST /transcodely.v1.UserService/Get

Parameters

ParameterTypeRequiredDescription
idstringYesUser ID (e.g., usr_a1b2c3d4e5).

Returns

Returns a User object.

curl -X POST https://api.transcodely.com/transcodely.v1.UserService/Get 
  -H "Authorization: Bearer ak_live_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{"id": "usr_a1b2c3d4e5"}'
{
  "user": {
    "id": "usr_a1b2c3d4e5",
    "email": "jane@acme.com",
    "email_verified": true,
    "first_name": "Jane",
    "last_name": "Doe",
    "status": "active",
    "last_login_at": "2025-02-28T09:15:00Z",
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-02-28T09:15:00Z"
  }
}

Update current user

Update the authenticated user’s display name. Email and verification status are synced from WorkOS and cannot be changed here.

Does not require X-Organization-ID header.

POST /transcodely.v1.UserService/UpdateMe

Parameters

ParameterTypeRequiredDescription
first_namestringNoNew first name (max 100 chars).
last_namestringNoNew last name (max 100 chars).

Returns

Returns the updated User object.

curl -X POST https://api.transcodely.com/transcodely.v1.UserService/UpdateMe 
  -H "Authorization: Bearer ak_live_abc123" 
  -H "Content-Type: application/json" 
  -d '{
    "first_name": "Jane",
    "last_name": "Smith"
  }'
{
  "user": {
    "id": "usr_a1b2c3d4e5",
    "email": "jane@acme.com",
    "email_verified": true,
    "first_name": "Jane",
    "last_name": "Smith",
    "status": "active",
    "last_login_at": "2025-02-28T09:15:00Z",
    "created_at": "2025-01-10T08:00:00Z",
    "updated_at": "2025-02-28T15:30:00Z"
  }
}

List users

List users in an organization. Requires admin permission.

Requires: X-Organization-ID header.

POST /transcodely.v1.UserService/List

Parameters

ParameterTypeRequiredDescription
statusstringNoFilter by status: active, suspended, or deleted.
paginationobjectNoPagination parameters. See Pagination.

Returns

Returns a list of User objects and pagination metadata.

curl -X POST https://api.transcodely.com/transcodely.v1.UserService/List 
  -H "Authorization: Bearer ak_live_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{
    "status": "active",
    "pagination": {"limit": 20}
  }'
{
  "users": [
    {
      "id": "usr_a1b2c3d4e5",
      "email": "jane@acme.com",
      "email_verified": true,
      "first_name": "Jane",
      "last_name": "Doe",
      "status": "active",
      "last_login_at": "2025-02-28T09:15:00Z",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-02-28T09:15:00Z"
    },
    {
      "id": "usr_q2w3e4r5t6",
      "email": "bob@acme.com",
      "email_verified": true,
      "first_name": "Bob",
      "last_name": "Johnson",
      "status": "active",
      "created_at": "2025-01-20T14:00:00Z",
      "updated_at": "2025-02-15T11:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "",
    "total_count": 2
  }
}

For managing organization members, roles, and permissions, see Memberships.