Authenticator management API

The authenticator management API is part of the REST API for STA. To get started with the API, you need the API key, endpoint URL, tenant code, and API documentation URL.

The API includes the following methods for managing your FIDO authenticators:

• Retrieve authenticators (GET): Get the list of all authenticators for a specific user.

• Create an authenticator (POST): Add an authenticator for a user.

• Retrieve a specific authenticator (GET): List the full details of a FIDO authenticator for a specific user.

• Delete an authenticator (DELETE): Delete a user's authenticator.

• Update an authenticator (PATCH): Update the authenticator details for a specific user.

Limitations of the authenticator management API

The authenticator API is currently limited to FIDO authenticators.

• When you PATCH a FIDO authenticator that has an existing friendly name, the friendly name cannot be blank or empty.

• The only allowed status changes using the API are from suspended to active, and from active to suspended. The status changes from pending to active after the user successfully completes the activation flow.

Retrieve authenticators (GET)

GET /api/v1/tenants/{tenantCode}/users/{userId}/authenticators

Lists all authenticators for a user who is identified by their user ID.

Sample request

GET /api/v1/tenants/{tenantCode}/users/{userId}/authenticators?pageIndex={page}&pageSize={pageSize}

Authenticator response

The response is a JSON list of list of authenticators for the user, and the pagination links. Each authenticator includes the following information:

FIDO authenticators have the following metadata:

• aaguid: (string) The Authenticator Attestation Globally Unique Identifier (AAGUID) is an identifier for FIDO2 security keys.

• friendlyName: (string) The friendly alias for the authenticator.

• rpId: (string) The identifier of the relying party. For example, the rpID can be the domain of the relying party.

• signatureCounter: (integer) The counter that counts the number of successful authentications.

• coseAlgoId: (integer) The CBOR Object Signing and Encryption (COSE) algorithm identifier that was used.

• provenance: (string) The provenance of the authenticator is either imported or inline. It indicates whether the authenticator was added in STA or was imported using the API.

Sample response

{
  "page": {
    "totalItems": 1,
    "pageIndex": 0,
    "pageSize": 10,
    "totalPages": 1,
    "items": [
      {
        "id": "h_0I4nKMO0wwXZRlK3zwT",
        "type": "FIDO",
        "state": "active",
        "lastUsedAuthnDateTime": "2023-01-26T20:52:42.7132811Z",
        "lastSuccessAuthnDateTime": "2023-01-26T20:52:42.7132815Z",
        "createdDateTime": "2023-01-26T20:52:42.7132817+00:00",
        "metadata": {
          "aaguid": "7a98c250-6808-11cf-b73b-00aa00b677a7",
          "friendlyName": "Friendly Name",
          "rpId": "awesomesite.net",
          "signatureCounter": 1,
          "coseAlgoId": -7,
          "provenance": "imported"
        }
      }
    ]
  },
  "links": {
    "first": "https://server/api/v1/tenants/abcdef/users?pageIndex=0&pageSize=10",
    "self": "https://server/api/v1/tenants/abcdef/users?pageIndex=0&pageSize=10",
    "last": "https://server/api/v1/tenants/abcdef/users?pageIndex=2&pageSize=10",
    "skip": "https://server/api/v1/tenants/abcdef/users?pageIndex=2&pageSize=10",
    "prev": "https://server/api/v1/tenants/abcdef/users?pageIndex=0&pageSize=10",
    "next": "https://server/api/v1/tenants/abcdef/users?pageIndex=1&pageSize=10"
  },
  "itemType": "Authenticator"
}

Responses

200 - Ok

Returns the list of authenticators and the pagination links.

400 - Bad request

• The tenantCode cannot be null or empty.
• The page index must be greater than or equal to 0. Parameter name: pageIndex
• The page size must be between 1 and 20. Parameter name: pageSize
• Object-Id-Format must be either base64(default) or hex. Parameter name: Object-Id-Format
• Other messages in the following format:

  {
  "errors":
  {
  "pageIndex": [ “The value ‘value’ is not valid.” ] },
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": “value of HttpContext.TraceIdentifier”
  }
  

401 - Unauthorized

Messages:

• No API key found in request.
• You do not have permission to access this tenant.
• Invalid authentication credentials.

404 - Not found

Messages:

• The tenant code ‘tenantCode’ does not exist.
• base64 userId ‘userId’ was not found.
• hex userId ‘userId’ was not found.

500 - Internal server error

Messages:

• Authenticator Service Exception.
• Internal Server Error.

Create an authenticator (POST)

POST /api/v1/tenants/{tenantCode}/users/{userId}/authenticators

Adds an authenticator for a specific user.

If you use an external credential management system (CMS) to manage authenticators, the CMS can use this method to export those authenticators into STA.

Each new authenticator is in the pending state until the user confirms their identity and activates their assigned authenticator.

Request data

The authenticator data to add must be in the message body as a JSON object. It includes the following information:

FIDO authenticators have the following metadata:

• attestation: Contains the attestation data for the requested authenticator:

  • clientDataJson: (string) ClientDataJson is a base64URL and UTF-8 encoded JSON serialization of client data.

  • attestationObject: (string) AttestationObject is a base64URL encoded string of Concise Binary Object Representation (CBOR) encoded content.

  • friendlyName: (string) The friendly alias for the authenticator.

Sample request

{
  "type": "FIDO",
  "metadata": {
    "attestation": {
      "clientDataJson": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiQUFBQmVCNzhJWHEyX3VRVTdlTkpjcTZVQ1ZuU25YMXEiLCJvcmlnaW4iOiJodHRwczovL215LnJwLmNvbSJ9",
      "attestationObject": "v2hhdXRoRGF0YVkCMNgdVDX-D2Z2KO2Dxum_NUfDXAo_l4_2cklwH4s5W3VGRQAAAAHDxRLsjn8R6qkVzxLLoAQmAawO7NlmO0TwDD_knBfIG-Yf9IELGtxBSaTHg1Xp9UjGgKJMFqUYp4MMzDHMHYQ4Xd98415WyXkTT2o2KOglgZZ5lTZ56A9Tdo1A4jKxa3YHJZZej0-hE7t1hHimJ9rpnmYY43teQnRVOP9lPc5Yp9vpV7YuN8W_Arb5bkyF_-aeOgDhEYuFlRaxoxiI-ASws0RLBbMkqyIVD5pQvhpmzOZt0MqH26FoEVf1fDd2WRepLrlARCUDecBlbgcN7hBLAmPmztYDDyR7jKznoOLXwzIwXKsnjfUef0wQnhqyyRmuX22NTNIFO_U_b4m9IwZhnntDGGzqG2fg6q_Mt23sxIA5qhdMgRZf7E9UejCmc418AzoLAhpQ-syUn8SCPT5xsUB-7sj7Hbhdy7OxcHtK7dkmIcVy_lW2CyP0zo_UnATziigcC1BelBcwA57nK6vV__5_0t5oAC-_d4TQftA9Fvu2gKCkiNXkxV5qI3gFVBEtkmIJfyyXrq1NevhIuROYXHVJKjD552jfiYkXOKw18iWyLh1jieueko5jkN_ptnbWj7ZCU_qBNhsc410WeaUBAgMmIAEhWCDOlb3nwM2QKKztsiBbZZNvw8JPs95AVJjst2TbIs2CDyJYIK2oFR4qAjngHRvNdCtFEkxZHBYoBs4Q6gQ9hKYMlFj0Z2F0dFN0bXS_Y3ZlcmgxMjY4NTAyM2hyZXNwb25zZVkIKWV5SmhiR2NpT2lKRlV6STFOaUlzSW5nMVl5STZXeUpOU1VsQ1pVUkRRMEZTTW1kQmQwbENRV2RKUWtGVVFVdENaMmR4YUd0cVQxQlJVVVJCYWtKTlRWSkpkMFZCV1VSV1VWRkxSRUZzVkdGSFJubGpSWGhvV1drMGVFNXFRVEJDWjA1V1FrRk5UVXhZVG5kamJXeDFXbmt4ZWxwWFRqRmpiV3d3WlZNeE0xcFhTbWhrV0ZKdlltbENNRnBZVGpCSlIyeDFaRWRXZVdKWFZtdGhWMFl3V2xOQ1JGRlVRV2RHZHpCM1RVUkJlRTFFUlhkTlJFRjNUVVJDWVVkQk9IbFBWR3MxVFZSSmVrMVVTWHBPVkdzeFQxWnZkMGhVUldKTlFtdEhRVEZWUlVGNFRWTlpXRkl3V2xoT01FeHRSblZhU0VwMllWZFJkVmt5T1hSTlJtdDNSWGRaU0V0dldrbDZhakJEUVZGWlNVdHZXa2w2YWpCRVFWRmpSRkZuUVVWcFIxUjNVQ3RYVm1SdlJGWnVUelJGVEhCb1QwaFFLelJGU0hwdFFrdGlZVkJyZUU1UmJ5czFkMFpZZWxOdUwzUTJVRzlhWTA1MmN5c3hNMVZIZDBvNVEyZ3JhVFZHYTI1a1FtTmtSSGw2ZEU5dk9XcHlOazFrVFVKemQwUkJXVVJXVWpCVVFrRlZkMEYzUlVJdmVrRk1RbWRPVmtoUk9FVkNRVTFEUVdkUmQwTm5XVWxMYjFwSmVtb3dSVUYzU1VSVFVVRjNVbWRKYUVGTVZVdEdOVmRuVjJkS1JIcG5ZV1U1TkdWcVptaFlaaXN4TTNRM00ySXlaV2xITlV0cVV6RnZkVlJqUVdsRlFXOVpValJSUm5WbVlsUTFheTlWYVcxSk9XbzJUVFZqYjJKeE4xVnJjbWw2ZFU1alFYaElVRk5HUldNOUlpd2lUVWxKUWpGcVEwTkJXSFZuUVhkSlFrRm5TVkZFVW1ncmNWcHpjRXhFTmtGeGJGZEJNVXA1U1dwRVFVdENaMmR4YUd0cVQxQlJVVVJCYWtKRlRWSkpkMFZCV1VSV1VWRkxSRUZzVkdGSFJubGpSWGhvV1drMGVFeHFRWE5DWjA1V1FrRk5UVXBZVG5kamJXeDFXbmt4ZWxwWFRqRmpiV3d3WlZNeE0xcFhTbWhrV0ZKdlltbENNRnBZVGpCSlNFcDJZak5SWjFFd1JYZEpRbU5PVFZSamQwOVVTWGxOUkUxNFQxUkZlRmRvWjFCTmFrVjRUbnBCTkUxcWEzZE5la1UxVFZSR1lVMUZkM2hGYWtGUlFtZE9Wa0pCYjAxRFZrNXZXVmhLZDFSSFJtbE1ha1V5VFVSUlIwRXhWVVZCZDNkMFl6TkNlV0ZYTlc1TVdFNXNXVE5XZVdGWVVqVk1XR1JzV1cxR01XUkhhSFZKU0ZKc1l6TlJaMkZYTlRCYVdFcDBXbGRTY0ZsWVVteEpSVTVDVFVacmQwVjNXVWhMYjFwSmVtb3dRMEZSV1VsTGIxcEplbW93UkVGUlkwUlJaMEZGVVRSMVdtWjNPWFJ4TlVSMWNXaDJNMk13Um5GVGVYQTVWQ3RRV1VJek5Xa3paa1poWjNkT2JuaERNVWRSVFU5cVl6Sk5RU3RrVTBvM01sTm1OMnBXUTJGV1RtSjVTMHBMTDNSdlFUZFBkbkowZERsWlpEWk9SazFGVFhkRloxbEVWbEl3VkVGUlNDOUNRV2QzUW1kRlFpOTNTVUpCUkVGUFFtZE9Wa2hST0VKQlpqaEZRa0ZOUTBGUldYZElVVmxFVmxJd1QwSkNXVVZHUzFRMGFUSjZWblJ1VWpocGFFVnBibXBVVDJVcldVaHJjMWxrVFVGdlIwTkRjVWRUVFRRNVFrRk5RMEV3YTBGTlJWbERTVkZFUjNreVFYbEVNV1psTmxnMUt6VmlkWGRWYWtGV1psTjNTbXhDYkZCclFqZFhRaXQxY2xGM1NGTnNVVWxvUVVzdlpsQkxaWFJ3ZFcwek1YTkZVbm8yTTA5YWVIWnNOVzEyYTNveVEyNDNWbWxXVFhSUmF6VjZValFpWFgwLmV5SnViMjVqWlNJNkltNVlNVEpuYUZsQmRVcHVWa3RoZEhWYWIxWkpXak14WTFGblZ6bGxVbVJyVVhsWGEwdDBXakpKUjNNaUxDSjBhVzFsYzNSaGJYQk5jeUk2TVRZd05qZ3dNalE1T1RJd01pd2lZWEJyVUdGamEyRm5aVTVoYldVaU9pSmpiMjB1WVc1a2NtOXBaQzVyWlhsemRHOXlaUzVoYm1SeWIybGthMlY1YzNSdmNtVmtaVzF2SWl3aVlYQnJRMlZ5ZEdsbWFXTmhkR1ZFYVdkbGMzUlRhR0V5TlRZaU9sc2lZbk5pTkM5WFVXUmhZVTlYV1VOa0wybzVUMHBwVVhCbk4ySXdhWGRHWjBGakwzcDZRVEYwUTJaM1JUMGlYU3dpWVhCclJHbG5aWE4wVTJoaE1qVTJJam9pWkUwdlRGVklVMGs1VTJ0UmFGcElTSEJSVjFKdWVrb3pUWFoyUWpKQlRsTmhkWEZaUVVGaVV6SktaejBpTENKamRITlFjbTltYVd4bFRXRjBZMmdpT25SeWRXVXNJbUpoYzJsalNXNTBaV2R5YVhSNUlqcDBjblZsZlEuT0c2VXM4NXEyenVSOWZHUzlnMzZ4ajgwR3N6QllQWDdmRnVoSjRhdm5hb2lNaUUwUmx3THg5UVZaLThlVnNlR2tzSFh3b1U4VmlLVEUwQ1V1b0Q1cHf_Y2ZtdHFhbmRyb2lkLXNhZmV0eW5ldP8"
    },
    "friendlyName": "My_TouchPass_B"
  }
}

Responses

200 - Ok

Authenticator imported.

400 - Bad Request

Messages:

• The tenantCode cannot be null or empty.
• The userId cannot be null or empty.
• Object-Id-Format must be either base64 or hex. Parameter name: Object-Id-Format
• Authenticator cannot be null.
• AttestationObject is not base64URL encoded.
• ClientDataJson is not base64URL encoded.

401 - Unauthorized

Messages:

• No API key found in request.
• You do not have permission to access this tenant.
• Invalid authentication credentials.

403 - Forbidden

Messages:

• Your current product plan does not include this functionality.
• Unable to import the FIDO authenticator, because importing via the API is disabled on the STA Access Management console.

404 - Not found

Messages:

• base64 userId ‘userId’ was not found.
• hex userId ‘userId’ was not found.
• The tenant code ‘tenantCode’ does not exist.

409 - Conflict

Messages:

• The authenticator is already in use.

500 - Internal server error

Messages:

• Authenticator Service Exception.
• Internal Server Error.

Retrieve a specific authenticator (GET)

GET /api/v1/tenants/{tenantCode}/users/{userId}/authenticators/{authenticatorId}

Gets the details for a specific authenticator based on its credential ID.

Authenticator response

The response is a JSON list of the authenticator details, and the pagination links. The authenticator includes the following information:

FIDO authenticators have the following metadata:

• aaguid: (string) The Authenticator Attestation Globally Unique Identifier (AAGUID) is an identifier for FIDO2 security keys.

• friendlyName: (string) The friendly alias for the authenticator.

• rpId: (string) The identifier of the relying party. For example, the rpID can be the domain of the relying party.

• signatureCounter: (integer) The counter that counts the number of successful authentications.

• coseAlgoId: (integer) The CBOR Object Signing and Encryption (COSE) algorithm identifier that was used.

• provenance: (string) The provenance of the authenticator is either imported or inline. It indicates whether the authenticator was added in STA or was imported using the API.

Sample response

{
  "id": "h_0I4nKMO0wwXZRlK3zwTo9lGukSBc2gfsXNiBj5RE7lHlZqR4OIGQ5HDzNW2sWZ2jBYwZrcp4jtunLJcas4MMOm7rPLN3cG9WSLDL1AkjQkaBznTMV4um0yADpikpn4xOQ40DU9IHYV6Qj1tcJ77OUbqsn0E2dR4np7aguwc9JI1sKZFkJAD3fFDAZz7lHdMCj31xCbzsiv1SbBkK6Mxmb8myPlDEmAwTn0BUvuDLim2YZ3dzRpXbk0OaC1YmFi1EPHSGwg4X4TR4oc6PfdDXqJ1YuCAIX918c0hejPw8P9vNErLQ0a1uk6PpXvaY7t1XydeIpkdrxPuVTAm2Ewa6l1Ws9sADfc2OKaUsBVOve6BCYfXSQn-XJ8mtwHo4A5N_J__2mCY413AzVIxZmQkz6a-zp2Zq_G3-JgkFPaUE3xRDKXwbTRfuA4D0gg_uH64-rOekolEWu0Q2IXNSLQ_KQiu0NHHOFlDxeolehfeXh0V5JQz7_TdBIgEZGkKq988q_EsqyQCUYCp7D3u0CEc788uo255-_0gW5Dz0I4HlenKT84bIz9I21r25s",
  "type": "FIDO",
  "state": "active",
  "lastUsedAuthnDateTime": "2023-01-26T20:52:42.716131+00:00",
  "lastSuccessAuthnDateTime": "2023-01-26T20:52:42.7161319+00:00",
  "createdDateTime": "2023-01-26T20:52:42.7161321+00:00",
  "metadata": {
    "aaguid": "7a98c250-6808-11cf-b73b-00aa00b677a7",
    "friendlyName": "My_TouchPass_B",
    "rpId": "awesomesite.net",
    "signatureCounter": 1,
    "coseAlgoId": -7,
    "provenance": "imported"
  }
}

Responses

200 - Ok

Returns the authenticator details.

400 - Bad request

Messages:

• The tenantCode cannot be null or empty.
• The userId cannot be null or empty.
• The authenticatorId cannot be null or empty.
• Object-Id-Format must be either base64(default) or hex. Parameter name: Object-Id-Format.
• The authenticatorId is not base64URL encoded.

401 - Unauthorized

Messages:

• No API key found in request.
• You do not have permission to access this tenant.
• Invalid authentication credentials.

404 - Not found

Messages:

• The tenant code ‘tenantCode’ does not exist.
• base64 userId ‘userId’ was not found.
• hex userId ‘userId’ was not found.
• The authenticator ID ‘authenticatorId’ was not found.

500 - Internal server error

Messages:

• Authenticator Service Exception.
• Internal Server Error.

Remove an authenticator (DELETE)

DELETE /api/v1/tenants/{tenantCode}/users/{userId}/authenticators/{authenticatorId}

Deletes a specific authenticator for a user.

Responses

204 - No Content

Returns No Content when the authenticator is deleted.

400 - Bad request

Messages:

• The tenantCode cannot be null or empty.
• The userId cannot be null or empty.
• The authenticatorId cannot be null or empty.
• Object-Id-Format must be either base64(default) or hex. Parameter name: Object-Id-Format.
• The authenticatorId is not base64URL encoded.
• The User Identifier Format Exception.

401 - Unauthorized

Messages:

• No API key found in request.
• You do not have permission to access this tenant.
• Invalid authentication credentials.

403 - Forbidden

Unable to delete the FIDO authenticator for the user, because the user is associated with the API key that authenticated this request, and the authenticator was imported with the API.

404 - Not found

Messages:

• The user userId ‘userId’ was not found.
• The tenant code ‘tenantCode’ does not exist.
• The authenticator ID ‘authenticatorId’ was not found.

500 - Internal server error

Messages:

• Authenticator Service Exception.
• Internal Server Error.

Update an authenticator (PATCH)

PATCH /api/v1/tenants/{tenantCode}/users/{userId}/authenticators/{authenticatorId}

Updates the details for the specified authenticator.

PATCH request

You can update the status and the friendly name of an authenticator.

The only allowed status changes using the API are from active to suspended, and from suspended to active. If the status is pending, you cannot update it using the API.

If the authenticator has an existing friendly name, the friendly name cannot be blank or empty.

FIDO authenticators have the following metadata:

• friendlyName: (string) The friendly alias for the authenticator.

Sample request

{
  "state": "active",
  "metadata": {
    "friendlyName": "My_TouchPass_B"
  }
}

Sample response

{
  "id": "h_0I4nKMO0wwXZRlK3zwTo9lGukSBc2gfsXNiBj5RE7lHlZqR4OIGQ5HDzNW2sWZ2jBYwZrcp4jtunLJcas4MMOm7rPLN3cG9WSLDL1AkjQkaBznTMV4um0yADpikpn4xOQ40DU9IHYV6Qj1tcJ77OUbqsn0E2dR4np7aguwc9JI1sKZFkJAD3fFDAZz7lHdMCj31xCbzsiv1SbBkK6Mxmb8myPlDEmAwTn0BUvuDLim2YZ3dzRpXbk0OaC1YmFi1EPHSGwg4X4TR4oc6PfdDXqJ1YuCAIX918c0hejPw8P9vNErLQ0a1uk6PpXvaY7t1XydeIpkdrxPuVTAm2Ewa6l1Ws9sADfc2OKaUsBVOve6BCYfXSQn-XJ8mtwHo4A5N_J__2mCY413AzVIxZmQkz6a-zp2Zq_G3-JgkFPaUE3xRDKXwbTRfuA4D0gg_uH64-rOekolEWu0Q2IXNSLQ_KQiu0NHHOFlDxeolehfeXh0V5JQz7_TdBIgEZGkKq988q_EsqyQCUYCp7D3u0CEc788uo255-_0gW5Dz0I4HlenKT84bIz9I21r25s",
  "type": "FIDO",
  "state": "active",
  "lastUsedAuthnDateTime": "2023-01-26T20:52:42.718233+00:00",
  "lastSuccessAuthnDateTime": "2023-01-26T20:52:42.718234+00:00",
  "createdDateTime": "2023-01-26T20:52:42.7182342+00:00",
  "metadata": {
    "aaguid": "7a98c250-6808-11cf-b73b-00aa00b677a7",
    "friendlyName": "My_TouchPass_B",
    "rpId": "awesomesite.net",
    "signatureCounter": 1,
    "coseAlgoId": -7,
    "provenance": "imported"
  }
}

Responses

200 - Ok

Returns the updated details for the authenticator.

400 - Bad request

Messages:

• The tenantCode cannot be null or empty.
• The userId cannot be null or empty.
• Object-Id-Format must be either base64 or hex. Parameter name: Object-Id-Format
• User Identifier Format.
• Authenticator cannot be null.
• The authenticatorId cannot be null or empty.
• The authenticatorId is not base64URL encoded.
• Operation Not Allowed Exception.

401 - Unauthorized

Messages:

• No API key found in request.
• You do not have permission to access this tenant.
• Invalid authentication credentials.

404 - Not found

Messages:

• The base64 userId ‘userId’ was not found.
• The hex userId ‘userId’ was not found.
• The tenant code ‘tenantCode’ does not exist.
• The authenticator ID ‘authenticatorId’ was not found.
• The User Not Found Exception.
• The Tenant Not Found Exception.
• The Authenticator Not Found Exception.

500 - Internal server error

Messages:

• Authenticator Service Exception.
• Internal Server Error.