Auth Service

The Privakey CX Auth Service is a server-deployed, secure API that acts as the broker between Request Origins and End Users.

The primary functions of the Auth Service include:

  1. Governing the binding of User accounts to Privakey CX.

  2. Receiving Generate Request POST requests from Request Origins.

  3. Sending Notifications to registered end user devices.

  4. Responding to GET queries for user, device and request information.

  5. Processing Process Request POST requests from Privakey CX libraries on end user devices.

  6. Responding to Request Origins configured callbacks upon challenge completion.

Auth Service Data Model Overview

The Auth Service can support multiple App Spaces. An App Space is defined by a deployed App and a single Authentication Provider.

For example, if a company wanted to support distinct apps for their customer-facing solutions and their employees' self-service applications, they would configure two different App Spaces.

Each App Space includes a minimal user model and each user can have many devices.

One or more Request Origins are configured within each App Space. The credentials issued for these Request Origins limit them to interacting with users and devices that have been bound to an account within the App Space.

Auth Service Access Control

All Privakey CX endpoints are authenticated by one of the following protocols:

  • Basic Header Authentication

  • HMAC Authentication

  • Session Token Authentication

  • JSON Web Token Authentication

Error Handling and Logging

All API endpoints conform to standard HTTP error handling. Primarily, the Privakey CX Auth Service will respond with a 404-error code for invalid endpoints and 400-error code for improperly formed requests. Unauthorized requests respond with a 401-error code.

Privakey CX Auth Service's logging level is configured in a JSON file. Log format conforms to standard syslog structures and includes timestamps, involved function and error event information. Logs do not include specific or sensitive event-level detail.

The Privakey CX Admin Service logs all events.

Data Protection

All Privakey CX Auth Service API endpoints are restricted to the proper type of requestor (i.e. Request Origins can only access relevant endpoints and are restricted from accessing endpoints leveraged by the CX Libraries).

The Privakey CX source code is protected using industry-standard code obfuscation and tamper-resistance tools.

Communication Security

Privakey CX Auth Service should use TLS for protecting connections to Request origins and the Privakey CX Mobile Libraries. We recommend you set this up during deployment.


Privakey CX configuration variables are defined in Environment Variables or in a configuration file. Privakey recommends and, in some instances, requires the use of Environment Variables for sensitive values.

Admin Portal

The Auth Service is extended with an Administrative Portal. The Admin Portal's primary functions include:

  1. Managing App Space organization

  2. Managing Access Credentials for Request Origins

  3. Managing allowable Callback URIs

  4. Managing credentials for the communication service

The Admin Portal is a service that allows administrative users to login in via an email and system generated credentials. Administrative users will have certain rights within the system based on their assigned roles to allow for responsible delegation of Privakey CX configuration.

API Input Validation

All Privakey CX API calls require authentication. Privakey CX Auth Service APIs are defined to expect structured content. The API Layer validates that all calls conform to this expected structure prior to calling Auth Service Logic. If a call does not conform the server responds with a 400 error.

Although some API fields could legitimately include hazardous characters (for example Request Content), Privakey CX protects against SQL injection and other potentially hazardous characters by ensuring this content is a properly escaped and typed string that is never processed.

However, it is important that implementers of Privakey CX protect the display of Request content from executing hazardous client side code.