Start a WebAuthN registration​
Start the registration of a new WebAuthN device (e.g. Passkeys) for a user. As a response the public key credential creation options are returned, which are used to verify the device.
Path Parameters
unique identifier of the user.
Request Body required
Possible values: non-empty
and <= 200 characters
Domain on which the user currently is or will be authenticated.
Possible values: [WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED
, WEB_AUTH_N_AUTHENTICATOR_PLATFORM
, WEB_AUTH_N_AUTHENTICATOR_CROSS_PLATFORM
]
Default value: WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED
Optionally specify the authenticator type of the passkey device (platform or cross-platform). If none is provided, both values are allowed.
code object
Request Body required
Possible values: non-empty
and <= 200 characters
Domain on which the user currently is or will be authenticated.
Possible values: [WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED
, WEB_AUTH_N_AUTHENTICATOR_PLATFORM
, WEB_AUTH_N_AUTHENTICATOR_CROSS_PLATFORM
]
Default value: WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED
Optionally specify the authenticator type of the passkey device (platform or cross-platform). If none is provided, both values are allowed.
code object
Request Body required
Possible values: non-empty
and <= 200 characters
Domain on which the user currently is or will be authenticated.
Possible values: [WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED
, WEB_AUTH_N_AUTHENTICATOR_PLATFORM
, WEB_AUTH_N_AUTHENTICATOR_CROSS_PLATFORM
]
Default value: WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED
Optionally specify the authenticator type of the passkey device (platform or cross-platform). If none is provided, both values are allowed.
code object
- 200
- 403
- 404
- default
WebAuthN registration successfully started
Schema
details object
unique identifier of the WebAuthN registration.
{
"details": {
"sequence": "2",
"changeDate": "2024-03-27T10:05:49.787Z",
"resourceOwner": "69629023906488334"
},
"webAuthNId": "163840776835432705",
"publicKeyCredentialCreationOptions": {
"publicKey": {
"attestation": "none",
"authenticatorSelection": {
"userVerification": "required"
},
"challenge": "XaMYwWOZ5hj6pwtwJJlpcI-ExkO5TxevBMG4R8DoKQQ",
"excludeCredentials": [
{
"id": "tVp1QfYhT8DkyEHVrv7blnpAo2YJzbZgZNBf7zPs6CI",
"type": "public-key"
}
],
"pubKeyCredParams": [
{
"alg": -7,
"type": "public-key"
}
],
"rp": {
"id": "localhost",
"name": "ZITADEL"
},
"timeout": 300000,
"user": {
"displayName": "Tim Mohlmann",
"id": "MjE1NTk4MDAwNDY0OTk4OTQw",
"name": "tim"
}
}
}
}
Schema
details object
unique identifier of the WebAuthN registration.
{
"details": {
"sequence": "2",
"changeDate": "2024-03-27T10:05:49.787Z",
"resourceOwner": "69629023906488334"
},
"webAuthNId": "163840776835432705",
"publicKeyCredentialCreationOptions": {
"publicKey": {
"attestation": "none",
"authenticatorSelection": {
"userVerification": "required"
},
"challenge": "XaMYwWOZ5hj6pwtwJJlpcI-ExkO5TxevBMG4R8DoKQQ",
"excludeCredentials": [
{
"id": "tVp1QfYhT8DkyEHVrv7blnpAo2YJzbZgZNBf7zPs6CI",
"type": "public-key"
}
],
"pubKeyCredParams": [
{
"alg": -7,
"type": "public-key"
}
],
"rp": {
"id": "localhost",
"name": "ZITADEL"
},
"timeout": 300000,
"user": {
"displayName": "Tim Mohlmann",
"id": "MjE1NTk4MDAwNDY0OTk4OTQw",
"name": "tim"
}
}
}
}
Schema
details object
unique identifier of the WebAuthN registration.
{
"details": {
"sequence": "2",
"changeDate": "2024-03-27T10:05:49.787Z",
"resourceOwner": "69629023906488334"
},
"webAuthNId": "163840776835432705",
"publicKeyCredentialCreationOptions": {
"publicKey": {
"attestation": "none",
"authenticatorSelection": {
"userVerification": "required"
},
"challenge": "XaMYwWOZ5hj6pwtwJJlpcI-ExkO5TxevBMG4R8DoKQQ",
"excludeCredentials": [
{
"id": "tVp1QfYhT8DkyEHVrv7blnpAo2YJzbZgZNBf7zPs6CI",
"type": "public-key"
}
],
"pubKeyCredParams": [
{
"alg": -7,
"type": "public-key"
}
],
"rp": {
"id": "localhost",
"name": "ZITADEL"
},
"timeout": 300000,
"user": {
"displayName": "Tim Mohlmann",
"id": "MjE1NTk4MDAwNDY0OTk4OTQw",
"name": "tim"
}
}
}
}
Returned when the user does not have permission to access the resource.
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
Returned when the resource does not exist.
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
An unexpected error response.
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
Schema
details object[]
{
"code": 0,
"message": "string",
"details": [
{
"@type": "string"
}
]
}
POST /v3alpha/users/:userId/webauthn
Authorization
name: OAuth2type: oauth2scopes:openid,urn:zitadel:iam:org:project:id:zitadel:aud
flows: { "authorizationCode": { "authorizationUrl": "$CUSTOM-DOMAIN/oauth/v2/authorize", "tokenUrl": "$CUSTOM-DOMAIN/oauth/v2/token", "scopes": { "openid": "openid", "urn:zitadel:iam:org:project:id:zitadel:aud": "urn:zitadel:iam:org:project:id:zitadel:aud" } } }
Request
Request
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'
curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/users/:userId/webauthn' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"domain": "my-domain.zitadel.cloud",
"authenticatorType": "WEB_AUTH_N_AUTHENTICATOR_UNSPECIFIED",
"code": {
"id": "e2a48d6a-362b-4db6-a1fb-34feab84dc62",
"code": "SKJd342k"
}
}'