Zum Hauptinhalt springen

Authenticate yourself to get an access token

POST/v2/authenticate
API-Version
v2
Request-Methode
POST
Operation-ID
user-authenticate

Request​

Responses​

Format
application/json
Beschreibung

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"
}

Format
application/json
Beschreibung

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 von string (einer von: totp, passkey, email)required

    More values may be added in the future; clients must ignore values they do not know.

    • Array[
      • *string (einer von: totp, passkey, email)
      ]
  • name"SecondFactorRequired"
  • passkeyChallengeobject

    A challenge for signing in or confirming an action with a passkey. Run navigator.credentials.get() with options and send challengeId together with the resulting credential.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 to PublicKeyCredential.parseRequestOptionsFromJSON()‍ and the result as publicKey to navigator.credentials.get(). Send the resulting credential back as credential.toJSON()‍ together with the challengeId the options came with. Binary values are base64url-encoded without padding.

      • allowCredentialsArray von 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 von 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
      • hintsArray von string

        Hints for the browser which authenticator to offer. Not set by this API.

        • Array[
          • *string
          ]
      • rpIdstringrequired

        The relying party, selected from the Origin header 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"
}

Kein Response-Inhalt angegeben.

Nutzungsbeispiele​

$ 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();

Auf dieser Seite