Authenticator management API

The authenticator management API is part of the SAS Management API. To get started, you need the client credentials, OAuth2 token URL, base API URL, tenant code, and API documentation URL — see Getting started with the SAS Management API.

The API includes the following methods for managing 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 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 authenticators for the user, plus pagination links. Each authenticator includes:

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 used.

• provenance: (string) Either imported or inline. Indicates whether the authenticator was added in the SAS PCE Enterprise Virtual Appliance or imported via 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 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:

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

401 - Unauthorized:

• No API key found in request.

• You do not have permission to access this tenant.

• Invalid authentication credentials.

404 - Not found:

• The tenant code 'tenantCode' does not exist.

• base64 userId 'userId' was not found.

• hex userId 'userId' was not found.

500 - Internal server error:

• Authenticator Service Exception.

• Internal Server Error.

Create an authenticator (POST)

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

Before running the POST endpoint, run below query in your SAS database. It will not be required from after next GA release.

DECLARE @tenantCode NVARCHAR(50) = '';

INSERT INTO ApplicationConfigurations VALUES ( 0, (SELECT TOP 1 orgID FROM SelfServicePolicy WHERE urlCode = @tenantCode), 'staconsole', 4, 0, 'FIDO_SETTINGS', CONVERT(VARBINARY(MAX), '{"FIDO_AUTHENTICATOR_IMPORT_ENABLED":true,"MAX_AUTHENTICATORS":5}') );

DECLARE @tenantCode NVARCHAR(50) = '';

UPDATE OrgServices SET productPlan = 2 WHERE orgID = (SELECT TOP 1 orgID FROM SelfServicePolicy WHERE urlCode = @tenantCode);

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 the SAS PCE Enterprise Virtual Appliance.

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:

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 CBOR encoded content.

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

Sample request

{
  "type": "FIDO",
  "metadata": {
    "attestation": {
      "clientDataJson": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiQUFBQmVCNzhJWHEyX3VRVTdlTkpjcTZVQ1ZuU25YMXEiLCJvcmlnaW4iOiJodHRwczovL215LnJwLmNvbSJ9",
      "attestationObject": "v2hhdXRoRGF0YVkCMNgdVDX-D2Z2KO2Dxum_NUfDXAo_l4_2cklwH4s5W3VGRQAAAAHDxRLsjn8R6qkVzxLLoAQm...truncated...Y2ZtdHFhbmRyb2lkLXNhZmV0eW5ldP8"
    },
    "friendlyName": "My_TouchPass_B"
  }
}

Responses

200 - Ok: Authenticator imported.

400 - Bad Request:

• 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:

• No API key found in request.

• You do not have permission to access this tenant.

• Invalid authentication credentials.

403 - Forbidden:

• Your current product plan does not include this functionality.

• Unable to import the FIDO authenticator, because importing via the API is disabled on the SAS PCE Enterprise Virtual Appliance Access Management console.

404 - Not found:

• base64 userId 'userId' was not found.

• hex userId 'userId' was not found.

• The tenant code 'tenantCode' does not exist.

409 - Conflict:

• The authenticator is already in use.

500 - Internal server error:

• 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 representation of the authenticator details. Attributes:

FIDO authenticator metadata fields: aaguid, friendlyName, rpId, signatureCounter, coseAlgoId, provenance (same descriptions as in the list GET above).

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:

• 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:

• No API key found in request.

• You do not have permission to access this tenant.

• Invalid authentication credentials.

404 - Not found:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• No API key found in request.

• You do not have permission to access this tenant.

• Invalid authentication credentials.

404 - Not found:

• 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:

• Authenticator Service Exception.

• Internal Server Error.