Exchange email/password for a session token.
curl --request POST \ --url https://stratum.example.com/v1/iam/login \ --header 'Content-Type: application/json' \ --data '{ "email": "hello@example.com", "password": "example", "mfaCode": "example" }'When the account still has its install-time password, the
login succeeds with passwordChangeRequired: true and a restricted
session (see Session). Choose a new password first.
after a node MFA recovery the login succeeds with
mfaEnrollmentRequired: true and a session restricted to enrolling a
new TOTP (see Session).
Request Bodyrequired
Section titled “Request Bodyrequired”object
TOTP or one-time recovery code. Required only for accounts with MFA enabled — omit it and the login returns 401 with code MFA_REQUIRED so the client knows to prompt..
Example generated
{ "email": "hello@example.com", "password": "example", "mfaCode": "example"}Responses
Section titled “Responses”Token issued.
object
object
Whether the user has an active TOTP MFA enrollment..
. Present (true) on the login response and GET /v1/iam/me
while the user still has the install-time password.
. Present (true) on the login response and GET /v1/iam/me
while a TOTP enrollment is owed after a node MFA recovery.
. The user still has the install-time password (a one-time
credential). Until POST /v1/iam/users/{userId}/password sets a new
one, this session may only call GET /v1/iam/me, POST /v1/iam/logout and that endpoint; everything else answers 403 PASSWORD_CHANGE_REQUIRED.
. A node recovery (stratum-bootstrap recover admin-mfa)
removed the user’s TOTP. Until a new one is enrolled and verified
(POST /v1/iam/users/{userId}/mfa/totp/enroll, then .../verify),
this session may only call those two, GET /v1/iam/me and POST /v1/iam/logout; everything else answers 403 MFA_ENROLLMENT_REQUIRED. When a password change is owed too, it
comes first.
Example
{ "user": { "state": "pending" }}Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Missing or invalid token.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Headers
Section titled “Headers”MFA_LOCKED: five wrong multi-factor codes within 15
minutes lock the account’s second factor for 15 minutes (shared with
the self-disable step-up). No code is checked during the lock, not
even a right one. Retry-After says when to try again.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Headers
Section titled “Headers”Seconds to wait before retrying.