- API Reference
- User
- Authenticate yourself to get an access token
Authenticate yourself to get an access token
Request
- cookieOnlyboolean
Only set the cookie and do not return cookie data.
- captchaTokenstring (≥ 1 characters, ≤ 2048 characters)
The response token of a solved captcha challenge, as issued by the captcha widget of the login form. A missing, unsolved or already used token is rejected with
CaptchaVerificationFailed(400). - emailstringrequired
The users Email-Address.
- passwordstringrequired
Password of the User.
Content-Type: application/json
{
"captchaToken": "string",
"email": "a.lovelace@example.com",
"password": "string"
}
{
"properties": {
"captchaToken": {
"description": "The response token of a solved captcha challenge, as issued by the captcha widget of the login\nform. A missing, unsolved or already used token is rejected with `CaptchaVerificationFailed` (400).\n",
"maxLength": 2048,
"minLength": 1,
"type": "string"
},
"email": {
"description": "The users Email-Address.",
"example": "a.lovelace@example.com",
"type": "string"
},
"password": {
"description": "Password of the User.",
"type": "string"
}
},
"required": [
"email",
"password"
],
"type": "object"
}
Responses
Your authentication request was successful and you've got an access token.
- expiresstring (date-time)required
The expiration date of the token.
- refreshTokenstringrequired
Refresh token to refresh your access token even after it has expired.
- tokenstringrequired
Public token to identify yourself against the api gateway.
Content-Type: application/json
{
"expires": "1985-10-26T01:21:00.000Z",
"refreshToken": "string",
"token": "string"
}
{
"properties": {
"expires": {
"description": "The expiration date of the token.",
"format": "date-time",
"type": "string"
},
"refreshToken": {
"description": "Refresh token to refresh your access token even after it has expired.",
"type": "string"
},
"token": {
"description": "Public token to identify yourself against the api gateway.",
"type": "string"
}
},
"required": [
"token",
"refreshToken",
"expires"
],
"type": "object"
}
A second factor is required. Call /authenticate-mfa with a valid multi factor code or passkey assertion.
availableSecondFactors lists the factors that can be used; it is empty if only a recovery code works.
passkeyChallenge is only set if passkey is available.
email is the only factor of a user without TOTP and passkeys: a confirmation code was mailed to the
user and has to be sent as multiFactorCode.
- availableSecondFactorsarray of string (one of: totp, passkey, email)required
More values may be added in the future; clients must ignore values they do not know.
- Array[
- *string (one of: totp, passkey, email)
]
- name"SecondFactorRequired"
- passkeyChallengeobject
A challenge for signing in or confirming an action with a passkey. Run
navigator.credentials.get()withoptionsand sendchallengeIdtogether with the resultingcredential.toJSON(). The challenge can be used once.- challengeIdstring (uuid)required
- optionsobjectrequired
Options for signing in with a passkey, as WebAuthn Level 3
PublicKeyCredentialRequestOptionsJSON. Pass the object unchanged toPublicKeyCredential.parseRequestOptionsFromJSON() and the result aspublicKeytonavigator.credentials.get(). Send the resulting credential back ascredential.toJSON() together with thechallengeIdthe options came with. Binary values are base64url-encoded without padding.- allowCredentialsarray of objectrequired
The passkeys of the user for this relying party. Empty for the passkey login, so the browser offers every passkey it has for the relying party.
- Array[
A passkey of the user, as WebAuthn Level 3
PublicKeyCredentialDescriptorJSON.- *object
A passkey of the user, as WebAuthn Level 3
PublicKeyCredentialDescriptorJSON.- idstringrequired
The credential id, base64url-encoded without padding.
- transportsarray of string
How the browser can reach the authenticator, as reported at registration (
internal,hybrid,usb,nfc,ble,smart-card).- Array[
- *string
]
- typestringrequired
The credential type, always
public-key.
]
- challengestringrequired
32 random bytes, base64url-encoded without padding. Can be used once.
- extensionsobject
WebAuthn Level 3
AuthenticationExtensionsClientInputsJSON. - hintsarray of string
Hints for the browser which authenticator to offer. Not set by this API.
- Array[
- *string
]
- rpIdstringrequired
The relying party, selected from the
Originheader of the request that created the challenge. - timeoutintegerrequired
Milliseconds until the challenge expires.
- userVerificationstringrequired
Always
required; the authenticator has to verify the user (biometrics or device PIN).
Content-Type: application/json
{
"availableSecondFactors": [
"totp"
],
"name": "SecondFactorRequired",
"passkeyChallenge": {
"challengeId": "6a1f0b1e-7d0c-4a43-9c1f-4f6c9b0f7a11",
"options": {
"allowCredentials": [
{
"id": "AN29uP9UVfVZ1X0WLKg3zA",
"transports": [
"hybrid",
"internal"
],
"type": "public-key"
}
],
"challenge": "rcUa1634YUaCsBeasroTVudBb4jNSnKzTGzJ9EdLlrA",
"rpId": "mittwald.de",
"timeout": 300000,
"userVerification": "required"
}
}
}
{
"properties": {
"availableSecondFactors": {
"description": "More values may be added in the future; clients must ignore values they do not know.",
"items": {
"enum": [
"totp",
"passkey",
"email"
],
"type": "string"
},
"type": "array"
},
"name": {
"enum": [
"SecondFactorRequired"
],
"type": "string"
},
"passkeyChallenge": {
"description": "A challenge for signing in or confirming an action with a passkey. Run `navigator.credentials.get()` with\n`options` and send `challengeId` together with the resulting `credential.toJSON()`. The challenge can be used\nonce.\n",
"properties": {
"challengeId": {
"example": "6a1f0b1e-7d0c-4a43-9c1f-4f6c9b0f7a11",
"format": "uuid",
"type": "string"
},
"options": {
"description": "Options for signing in with a passkey, as WebAuthn Level 3\n[`PublicKeyCredentialRequestOptionsJSON`](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptionsjson).\nPass the object unchanged to\n[`PublicKeyCredential.parseRequestOptionsFromJSON()`](https://www.w3.org/TR/webauthn-3/#sctn-parseRequestOptionsFromJSON)\nand the result as `publicKey` to `navigator.credentials.get()`. Send the resulting credential back as\n[`credential.toJSON()`](https://www.w3.org/TR/webauthn-3/#dom-publickeycredential-tojson) together with the\n`challengeId` the options came with. Binary values are base64url-encoded without padding.\n",
"example": {
"allowCredentials": [
{
"id": "AN29uP9UVfVZ1X0WLKg3zA",
"transports": [
"hybrid",
"internal"
],
"type": "public-key"
}
],
"challenge": "rcUa1634YUaCsBeasroTVudBb4jNSnKzTGzJ9EdLlrA",
"rpId": "mittwald.de",
"timeout": 300000,
"userVerification": "required"
},
"properties": {
"allowCredentials": {
"description": "The passkeys of the user for this relying party. Empty for the passkey login, so the browser offers every\npasskey it has for the relying party.\n",
"items": {
"description": "A passkey of the user, as WebAuthn Level 3\n[`PublicKeyCredentialDescriptorJSON`](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialdescriptorjson).\n",
"example": {
"id": "AN29uP9UVfVZ1X0WLKg3zA",
"transports": [
"hybrid",
"internal"
],
"type": "public-key"
},
"properties": {
"id": {
"description": "The credential id, base64url-encoded without padding.",
"example": "AN29uP9UVfVZ1X0WLKg3zA",
"type": "string"
},
"transports": {
"description": "How the browser can reach the authenticator, as reported at registration (`internal`, `hybrid`, `usb`,\n`nfc`, `ble`, `smart-card`).\n",
"example": [
"hybrid",
"internal"
],
"items": {
"type": "string"
},
"type": "array"
},
"type": {
"description": "The credential type, always `public-key`.",
"example": "public-key",
"type": "string"
}
},
"required": [
"type",
"id"
],
"type": "object"
},
"type": "array"
},
"challenge": {
"description": "32 random bytes, base64url-encoded without padding. Can be used once.",
"example": "rcUa1634YUaCsBeasroTVudBb4jNSnKzTGzJ9EdLlrA",
"type": "string"
},
"extensions": {
"description": "WebAuthn Level 3\n[`AuthenticationExtensionsClientInputsJSON`](https://www.w3.org/TR/webauthn-3/#dictdef-authenticationextensionsclientinputsjson).\n",
"type": "object"
},
"hints": {
"description": "Hints for the browser which authenticator to offer. Not set by this API.",
"items": {
"type": "string"
},
"type": "array"
},
"rpId": {
"description": "The relying party, selected from the `Origin` header of the request that created the challenge.",
"example": "mittwald.de",
"type": "string"
},
"timeout": {
"description": "Milliseconds until the challenge expires.",
"example": 300000,
"type": "integer"
},
"userVerification": {
"description": "Always `required`; the authenticator has to verify the user (biometrics or device PIN).",
"example": "required",
"type": "string"
}
},
"required": [
"challenge",
"rpId",
"allowCredentials",
"timeout",
"userVerification"
],
"type": "object"
}
},
"required": [
"challengeId",
"options"
],
"type": "object"
}
},
"required": [
"availableSecondFactors"
],
"type": "object"
}
Authentication failed because of wrong credentials, or the captcha token is missing, unsolved or
already used (CaptchaVerificationFailed).
- *
Content-Type: application/json
null
{
"anyOf": [
{
"type": "object",
"required": [
"type",
"validationErrors"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidationError"
]
},
"message": {
"type": "string",
"example": "Validation failed"
},
"validationErrors": {
"type": "array",
"items": {
"type": "object",
"required": [
"message",
"path",
"type"
],
"properties": {
"message": {
"type": "string",
"description": "The standard error message",
"example": "should be string"
},
"path": {
"type": "string",
"description": "The path to the part of the data that was validated. JavaScript property access notation (e.g., \".prop[1].subProp\") is used.\n",
"example": ".address.street"
},
"type": {
"type": "string",
"description": "ajv validation error type (e.g. \"format\", \"required\", \"type\") or own validation error types",
"example": "format"
},
"context": {
"type": "object",
"example": {
"format": "email"
},
"description": "The object with the additional information about the error that can be used to create custom error messages. Keys depend on the\ntype that failed validation (e.g. \"missingProperty\" for type \"required\")\n",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
]
}
Authentication failed because of wrong credentials.
- Alternativeobject
- type"ValidationError"required
- messagestring
- validationErrorsarray of objectrequired
- Array[
- *object
- messagestringrequired
The standard error message
- pathstringrequired
The path to the part of the data that was validated. JavaScript property access notation (e.g., ".prop[1].subProp") is used.
- typestringrequired
ajv validation error type (e.g. "format", "required", "type") or own validation error types
- contextobject
The object with the additional information about the error that can be used to create custom error messages. Keys depend on the type that failed validation (e.g. "missingProperty" for type "required")
- *string
]
- Alternativeobject
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"type": "ValidationError",
"message": "Validation failed",
"validationErrors": [
{
"message": "should be string",
"path": ".address.street",
"type": "format",
"context": {
"format": "email"
}
}
]
}
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"oneOf": [
{
"type": "object",
"required": [
"type",
"validationErrors"
],
"properties": {
"type": {
"type": "string",
"enum": [
"ValidationError"
]
},
"message": {
"type": "string",
"example": "Validation failed"
},
"validationErrors": {
"type": "array",
"items": {
"type": "object",
"required": [
"message",
"path",
"type"
],
"properties": {
"message": {
"type": "string",
"description": "The standard error message",
"example": "should be string"
},
"path": {
"type": "string",
"description": "The path to the part of the data that was validated. JavaScript property access notation (e.g., \".prop[1].subProp\") is used.\n",
"example": ".address.street"
},
"type": {
"type": "string",
"description": "ajv validation error type (e.g. \"format\", \"required\", \"type\") or own validation error types",
"example": "format"
},
"context": {
"type": "object",
"example": {
"format": "email"
},
"description": "The object with the additional information about the error that can be used to create custom error messages. Keys depend on the\ntype that failed validation (e.g. \"missingProperty\" for type \"required\")\n",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
},
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
]
}
Too many failed logins from your address. Wait until the lockout ends and try again.
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
The captcha could not be verified because the verification service did not answer
(CaptchaVerificationUnavailable). Retry with a new challenge.
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
An unexpected Error that occurred while handling the request
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
Usage examples
$ curl \
--fail \
--location \
-X POST \
-d '{"captchaToken":"string","email":"a.lovelace@example.com","password":"string"}' \
-H "Authorization: Bearer $MITTWALD_API_TOKEN" \
-H 'Content-Type: application/json' \
https://api.mittwald.de/v2/authenticate?cookieOnly=true
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.user.authenticate({
"data": {
"captchaToken": "string",
"email": "a.lovelace@example.com",
"password": "string"
},
"queryParameters": {
"cookieOnly": true
}
});
assertStatus(response, 200);
use \Mittwald\ApiClient\Generated\V2\Clients\User\Authenticate\AuthenticateRequest;
use \Mittwald\ApiClient\Generated\V2\Clients\User\Authenticate\AuthenticateRequestBody;
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));
// TODO: Please consult the properties and constructor signature of
// AuthenticateRequestBody to learn how to construct a valid instance
$body = new AuthenticateRequestBody(/* TODO: ... */);
$request = (new AuthenticateRequest(
body: $body
))
->withCookieOnly(true);
$response = $client->user()->authenticate($request);
var_dump($response->getBody();