Authenticate

POST

/iam/v1/users:authenticate

curl --request POST \
  --url https://example.com/iam/v1/users:authenticate \
  --header 'Content-Type: application/json' \
  --data '{ "email": "example", "password": "example" }'

Authenticates a user with email and password, returning a session token

Request Body ^required

Media type application/json

AuthenticateRequest

Request message for Authenticate. Carries the user’s email and password for password-based login.

object

email

required

The email address of the user

string

password

required

The password of the user

string

Example ^generated

{
  "email": "example",
  "password": "example"
}

Responses

200

OK

Media type application/json

AuthenticateResponse

Response message for Authenticate. Carries the freshly issued access + refresh token pair and their expiry timestamps.

object

access_token

The opaque access token used as Bearer credential for authenticated requests

string

access_token_expires_at

The expiration time of the access token

string format: date-time Output only

refresh_token

The opaque refresh token used to obtain new access tokens without re-authenticating

string

refresh_token_expires_at

The expiration time of the refresh token

string format: date-time Output only

access_token_hash

SHA-512 hex fingerprint of the access token. CLI/TUI clients use this as the stable session identifier — it matches the row’s iam.tokens.token_hash, so clients never need to compute SHA-512 themselves. Same field number on RefreshTokenResponse so the wire shape is symmetric across mint and rotation.

stringOutput only

Example ^generated

{
  "access_token": "example",
  "refresh_token": "example"
}

default

Default error response

Media type application/json

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

object

code

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

integer format: int32

message

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

string

details

A list of messages that carry the error details. There is a common set of message types for APIs to use.

Array<object>

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

object

@type

The type of the serialized message.

string

key

additional properties

any

Example ^generated

{
  "code": 1,
  "message": "example",
  "details": [
    {
      "@type": "example"
    }
  ]
}