Skip to main content

Create an OATH credential

POST 
/nevisidm/api/core/v1/:clientExtId/users/:userExtId/oath-credentials

Since: 2.71.0

Required permission(s): AccessControl.CredentialCreate,AccessControl.CredentialView,AccessControl.PolicyConfigurationView or SelfAdmin Role

Creates a new OATH credential for the specified user.

A label is required and will be embedded in the otpauth:// QR code URI returned in the response. The URI can be scanned by a mobile authenticator app (e.g. Google Authenticator, Microsoft Authenticator) to initialize the credential.

If a policy is specified, it must be of type OathPolicy. If omitted, the default OATH policy configured for the client is used. The policy determines the hashing algorithm, digit count, time period, and other OTP parameters.

The OATH secret is generated automatically by the server. If the policy is configured to prevent re-sharing the secret, the QR code URI is only available in the response of this creation endpoint. Subsequent GET requests will not include the URI.

In self-admin mode, a valid JWT token must be provided in the X-Token request header.

Request​

Path Parameters

    clientExtId stringrequired

    External ID of the client.

    Example: client-123
    userExtId stringrequired

    External ID of the user.

    Example: user-123

Body

required
    extId string

    The external ID of the OATH credential. If omitted, one will be generated automatically.

    policyExtId string

    The external ID of the policy to apply to this OATH credential.

    label stringrequired

    Possible values: non-empty

    The label used to identify this OATH credential in the authenticator app.

    stateName string

    Possible values: [initial, active, tmp-locked, fail-locked, reset-code, admin-changed, disabled, archived]

    The initial state of the credential.

Responses​

OATH credential created successfully

Schema
    created string

    Creation date of the entity.

    lastModified string

    Date when the entity was last modified.

    version int32

    Version used for optimistic locking.

    extId string

    The external ID of the credential.

    userExtId string

    The external ID of the user to whom the credential belongs.

    policyExtId string

    The external ID of the used policy.

    stateName string

    Possible values: [initial, active, tmp-locked, fail-locked, reset-code, admin-changed, disabled, archived]

    The state of the credential. Available values: initial, active, tmp-locked, fail-locked, reset-code, admin-changed, disabled, archived.

    stateChangeReason string

    Reason for the last state change of the password.

    stateChangeDetail string

    Reason detail for the last state change of the password.

    lastSuccessfulLoginDate string

    Timestamp of last successful login.

    successfulLoginCount int32

    Counts successful logins with this credential since last initialization or reset.

    lastFailedLoginDate string

    Date of last non-technical login failure, for example, wrong password.

    failedLoginCount int32

    Counts non-technical login failures since the last successful login, initialization or reset.

    modificationComment string

    Textual comment regarding the last modification.

    type string

    Possible values: [Password, Certificate, SecurID User Mapping, Ticket Authorization, Safeword User Mapping, OTP Card, Temporary Strong Password, Generic Credential, Kerberos, mTan, Vasco, PUK, URL Ticket, DevicePassword, MobileSignature, SAML Federation, Security Questions, Context Password, OATH, FIDO UAF Authenticator, Recovery Code, FIDO2 Authenticator]

    Type of credential.

    validity object

    Describes the validity period of the password.

    from string

    Start date of the entity's validity in ISO format.

    to string

    End date of the entity's validity in ISO format.

    uri string

    The generated QR code URI in otpauth:// format for initializing a mobile authenticator app.

    issuer string

    The service provider or application name associated with this OATH credential.

    authenticationMethod string

    Possible values: [TOTP, HOTP]

    The authentication method used by this OATH credential (e.g. TOTP for time-based, HOTP for counter-based).

    hashingAlgorithm string

    Possible values: [SHA1, SHA256, SHA512]

    The hashing algorithm used for OTP generation.

    digits string

    The number of digits in the generated one-time password.

    period int64

    The time window in seconds during which a TOTP token is valid.

    counter int64

    The HOTP counter value, incremented on each successful authentication.

    secret string

    The encrypted shared secret required to initialize a mobile authenticator app.

    label string

    The label used to identify this OATH credential in the authenticator app.

Loading...
Last updated on