User by ID

GET 
https://$CUSTOM-DOMAIN/v2/users/:userId

Returns the full user object (human or machine) including the profile, email, etc..

Request

Path Parameters

userId stringrequired

User ID of the user you like to get.

Responses

200

OK

application/json

Schema

Schema

details

object

sequence uint64

on read: the sequence of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

changeDate date-time

on read: the timestamp of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

resourceOwner resource_owner is the organization or instance_id an object belongs to (string)

creationDate date-time

user

object

userId string

details

object

sequence uint64

on read: the sequence of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

changeDate date-time

on read: the timestamp of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

resourceOwner resource_owner is the organization or instance_id an object belongs to (string)

creationDate date-time

state string

Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED, USER_STATE_INITIAL]

Default value: USER_STATE_UNSPECIFIED

current state of the user

username string

loginNames string[]

preferredLoginName string

human

object

one of type use human or machine

userId string

Unique identifier of the user.

state string

Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED, USER_STATE_INITIAL]

Default value: USER_STATE_UNSPECIFIED

current state of the user

username string

Username of the user, which can be globally unique or unique on organization level.

loginNames string[]

Possible usable login names for the user.

preferredLoginName string

Preferred login name of the user.

profile

object

Profile information of the user.

givenName string

Possible values: non-empty and <= 200 characters

familyName string

Possible values: non-empty and <= 200 characters

nickName string

Possible values: <= 200 characters

displayName string

Possible values: <= 200 characters

preferredLanguage string

Possible values: <= 10 characters

gender string

Possible values: [GENDER_UNSPECIFIED, GENDER_FEMALE, GENDER_MALE, GENDER_DIVERSE]

Default value: GENDER_UNSPECIFIED

avatarUrl string

avatar URL of the user

email

object

Email of the user, if defined.

email string

Possible values: non-empty and <= 200 characters

isVerified boolean

phone

object

Phone of the user, if defined.

phone string

Possible values: <= 200 characters

isVerified boolean

passwordChangeRequired boolean

User is required to change the used password on the next login.

passwordChanged date-time

The time the user last changed their password.

mfaInitSkipped date-time

The time the user last skipped MFA initialization.

machine

object

one of type use human or machine

name string

description string

hasSecret boolean

accessTokenType string

Possible values: [ACCESS_TOKEN_TYPE_BEARER, ACCESS_TOKEN_TYPE_JWT]

Default value: ACCESS_TOKEN_TYPE_BEARER

Type of access token to receive

Example (from schema)

{
  "details": {
    "sequence": "2",
    "changeDate": "2025-03-25T17:50:43.449Z",
    "resourceOwner": "69629023906488334",
    "creationDate": "2025-03-25T17:50:43.449Z"
  },
  "user": {
    "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
    "details": {
      "sequence": "2",
      "changeDate": "2025-03-25T17:50:43.450Z",
      "resourceOwner": "69629023906488334",
      "creationDate": "2025-03-25T17:50:43.450Z"
    },
    "state": "USER_STATE_UNSPECIFIED",
    "username": "minnie-mouse",
    "loginNames": [
      "gigi@zitadel.com",
      "gigi@zitadel.zitadel.ch"
    ],
    "preferredLoginName": "gigi@zitadel.com",
    "human": {
      "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
      "state": "USER_STATE_UNSPECIFIED",
      "username": "minnie-mouse",
      "loginNames": [
        "gigi@zitadel.com",
        "gigi@zitadel.zitadel.ch"
      ],
      "preferredLoginName": "gigi@zitadel.com",
      "profile": {
        "givenName": "Minnie",
        "familyName": "Mouse",
        "nickName": "Mini",
        "displayName": "Minnie Mouse",
        "preferredLanguage": "en",
        "gender": "GENDER_FEMALE",
        "avatarUrl": "https://api.zitadel.ch/assets/v1/avatar-32432jkh4kj32"
      },
      "email": {
        "email": "mini@mouse.com",
        "isVerified": true
      },
      "phone": {
        "phone": "+41791234567",
        "isVerified": true
      },
      "passwordChangeRequired": true,
      "passwordChanged": "2025-03-25T17:50:43.450Z",
      "mfaInitSkipped": "2025-03-25T17:50:43.450Z"
    },
    "machine": {
      "name": "zitadel",
      "description": "The one and only IAM",
      "hasSecret": "true",
      "accessTokenType": "ACCESS_TOKEN_TYPE_BEARER"
    }
  }
}

application/grpc

Schema

Schema

details

object

sequence uint64

on read: the sequence of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

changeDate date-time

on read: the timestamp of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

resourceOwner resource_owner is the organization or instance_id an object belongs to (string)

creationDate date-time

user

object

userId string

details

object

sequence uint64

on read: the sequence of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

changeDate date-time

on read: the timestamp of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

resourceOwner resource_owner is the organization or instance_id an object belongs to (string)

creationDate date-time

state string

Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED, USER_STATE_INITIAL]

Default value: USER_STATE_UNSPECIFIED

current state of the user

username string

loginNames string[]

preferredLoginName string

human

object

one of type use human or machine

userId string

Unique identifier of the user.

state string

Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED, USER_STATE_INITIAL]

Default value: USER_STATE_UNSPECIFIED

current state of the user

username string

Username of the user, which can be globally unique or unique on organization level.

loginNames string[]

Possible usable login names for the user.

preferredLoginName string

Preferred login name of the user.

profile

object

Profile information of the user.

givenName string

Possible values: non-empty and <= 200 characters

familyName string

Possible values: non-empty and <= 200 characters

nickName string

Possible values: <= 200 characters

displayName string

Possible values: <= 200 characters

preferredLanguage string

Possible values: <= 10 characters

gender string

Possible values: [GENDER_UNSPECIFIED, GENDER_FEMALE, GENDER_MALE, GENDER_DIVERSE]

Default value: GENDER_UNSPECIFIED

avatarUrl string

avatar URL of the user

email

object

Email of the user, if defined.

email string

Possible values: non-empty and <= 200 characters

isVerified boolean

phone

object

Phone of the user, if defined.

phone string

Possible values: <= 200 characters

isVerified boolean

passwordChangeRequired boolean

User is required to change the used password on the next login.

passwordChanged date-time

The time the user last changed their password.

mfaInitSkipped date-time

The time the user last skipped MFA initialization.

machine

object

one of type use human or machine

name string

description string

hasSecret boolean

accessTokenType string

Possible values: [ACCESS_TOKEN_TYPE_BEARER, ACCESS_TOKEN_TYPE_JWT]

Default value: ACCESS_TOKEN_TYPE_BEARER

Type of access token to receive

Example (from schema)

{
  "details": {
    "sequence": "2",
    "changeDate": "2025-03-25T17:50:43.451Z",
    "resourceOwner": "69629023906488334",
    "creationDate": "2025-03-25T17:50:43.451Z"
  },
  "user": {
    "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
    "details": {
      "sequence": "2",
      "changeDate": "2025-03-25T17:50:43.451Z",
      "resourceOwner": "69629023906488334",
      "creationDate": "2025-03-25T17:50:43.451Z"
    },
    "state": "USER_STATE_UNSPECIFIED",
    "username": "minnie-mouse",
    "loginNames": [
      "gigi@zitadel.com",
      "gigi@zitadel.zitadel.ch"
    ],
    "preferredLoginName": "gigi@zitadel.com",
    "human": {
      "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
      "state": "USER_STATE_UNSPECIFIED",
      "username": "minnie-mouse",
      "loginNames": [
        "gigi@zitadel.com",
        "gigi@zitadel.zitadel.ch"
      ],
      "preferredLoginName": "gigi@zitadel.com",
      "profile": {
        "givenName": "Minnie",
        "familyName": "Mouse",
        "nickName": "Mini",
        "displayName": "Minnie Mouse",
        "preferredLanguage": "en",
        "gender": "GENDER_FEMALE",
        "avatarUrl": "https://api.zitadel.ch/assets/v1/avatar-32432jkh4kj32"
      },
      "email": {
        "email": "mini@mouse.com",
        "isVerified": true
      },
      "phone": {
        "phone": "+41791234567",
        "isVerified": true
      },
      "passwordChangeRequired": true,
      "passwordChanged": "2025-03-25T17:50:43.451Z",
      "mfaInitSkipped": "2025-03-25T17:50:43.451Z"
    },
    "machine": {
      "name": "zitadel",
      "description": "The one and only IAM",
      "hasSecret": "true",
      "accessTokenType": "ACCESS_TOKEN_TYPE_BEARER"
    }
  }
}

application/grpc-web+proto

Schema

Schema

details

object

sequence uint64

on read: the sequence of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

changeDate date-time

on read: the timestamp of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

resourceOwner resource_owner is the organization or instance_id an object belongs to (string)

creationDate date-time

user

object

userId string

details

object

sequence uint64

on read: the sequence of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

changeDate date-time

on read: the timestamp of the last event reduced by the projection

on manipulation: the timestamp of the event(s) added by the manipulation

resourceOwner resource_owner is the organization or instance_id an object belongs to (string)

creationDate date-time

state string

Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED, USER_STATE_INITIAL]

Default value: USER_STATE_UNSPECIFIED

current state of the user

username string

loginNames string[]

preferredLoginName string

human

object

one of type use human or machine

userId string

Unique identifier of the user.

state string

Possible values: [USER_STATE_UNSPECIFIED, USER_STATE_ACTIVE, USER_STATE_INACTIVE, USER_STATE_DELETED, USER_STATE_LOCKED, USER_STATE_INITIAL]

Default value: USER_STATE_UNSPECIFIED

current state of the user

username string

Username of the user, which can be globally unique or unique on organization level.

loginNames string[]

Possible usable login names for the user.

preferredLoginName string

Preferred login name of the user.

profile

object

Profile information of the user.

givenName string

Possible values: non-empty and <= 200 characters

familyName string

Possible values: non-empty and <= 200 characters

nickName string

Possible values: <= 200 characters

displayName string

Possible values: <= 200 characters

preferredLanguage string

Possible values: <= 10 characters

gender string

Possible values: [GENDER_UNSPECIFIED, GENDER_FEMALE, GENDER_MALE, GENDER_DIVERSE]

Default value: GENDER_UNSPECIFIED

avatarUrl string

avatar URL of the user

email

object

Email of the user, if defined.

email string

Possible values: non-empty and <= 200 characters

isVerified boolean

phone

object

Phone of the user, if defined.

phone string

Possible values: <= 200 characters

isVerified boolean

passwordChangeRequired boolean

User is required to change the used password on the next login.

passwordChanged date-time

The time the user last changed their password.

mfaInitSkipped date-time

The time the user last skipped MFA initialization.

machine

object

one of type use human or machine

name string

description string

hasSecret boolean

accessTokenType string

Possible values: [ACCESS_TOKEN_TYPE_BEARER, ACCESS_TOKEN_TYPE_JWT]

Default value: ACCESS_TOKEN_TYPE_BEARER

Type of access token to receive

Example (from schema)

{
  "details": {
    "sequence": "2",
    "changeDate": "2025-03-25T17:50:43.453Z",
    "resourceOwner": "69629023906488334",
    "creationDate": "2025-03-25T17:50:43.453Z"
  },
  "user": {
    "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
    "details": {
      "sequence": "2",
      "changeDate": "2025-03-25T17:50:43.453Z",
      "resourceOwner": "69629023906488334",
      "creationDate": "2025-03-25T17:50:43.453Z"
    },
    "state": "USER_STATE_UNSPECIFIED",
    "username": "minnie-mouse",
    "loginNames": [
      "gigi@zitadel.com",
      "gigi@zitadel.zitadel.ch"
    ],
    "preferredLoginName": "gigi@zitadel.com",
    "human": {
      "userId": "d654e6ba-70a3-48ef-a95d-37c8d8a7901a",
      "state": "USER_STATE_UNSPECIFIED",
      "username": "minnie-mouse",
      "loginNames": [
        "gigi@zitadel.com",
        "gigi@zitadel.zitadel.ch"
      ],
      "preferredLoginName": "gigi@zitadel.com",
      "profile": {
        "givenName": "Minnie",
        "familyName": "Mouse",
        "nickName": "Mini",
        "displayName": "Minnie Mouse",
        "preferredLanguage": "en",
        "gender": "GENDER_FEMALE",
        "avatarUrl": "https://api.zitadel.ch/assets/v1/avatar-32432jkh4kj32"
      },
      "email": {
        "email": "mini@mouse.com",
        "isVerified": true
      },
      "phone": {
        "phone": "+41791234567",
        "isVerified": true
      },
      "passwordChangeRequired": true,
      "passwordChanged": "2025-03-25T17:50:43.453Z",
      "mfaInitSkipped": "2025-03-25T17:50:43.453Z"
    },
    "machine": {
      "name": "zitadel",
      "description": "The one and only IAM",
      "hasSecret": "true",
      "accessTokenType": "ACCESS_TOKEN_TYPE_BEARER"
    }
  }
}

403

Returned when the user does not have permission to access the resource.

application/json

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

application/grpc

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

application/grpc-web+proto

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

404

Returned when the resource does not exist.

application/json

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

application/grpc

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

application/grpc-web+proto

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

default

An unexpected error response.

application/json

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

application/grpc

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

application/grpc-web+proto

Schema

Schema

code int32
message string

details

object[]

Array [

@type string

]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

Request Collapse all

Base URL

https://$CUSTOM-DOMAIN

Auth

Bearer Token

Parameters

userId — pathrequired

ResponseClear

Click the Send API Request button above and see the response here!