Authentication

Updated: May 15, 2017

All clients connecting to SmartKey must be authenticated. Clients are classified as either users or applications. A user authenticates to SmartKey using a password. An application authenticates to SmartKey using either an API key or a TLS client certificate.

For both users and applications, the authentication flow operates as follows:

  • Make a request to the create session API, authenticated with the master credential (password, API key, or client certificate) and HTTP Basic authentication. If authentication is successful, SmartKey returns a “bearer token” which authenticates the client for the duration of a login session.
  • Make requests to other SmartKey APIs as desired, presenting the bearer token with each request. If the client is an application using certificate-based authentication, each request must also be authenticated with the client certificate.
  • When the session is no longer needed, it is recommended to use the terminate session API to log out.

SmartKey APIs may be available to users only, to applications only, or to both users and applications. For information about the client types allowed by each API, refer to the API reference.

User authentication using passwords

For user session establishment, the HTTP Basic authentication string is the Base64 encoding of the email and password separated by a colon. For example, to authenticate as test@example.com with password password, supply the following header with the create session request:

Authorization: Basic dGVzdEBleGFtcGxlLmNvbTpwYXNzd29yZA==

Application authentication using API keys

An API key is simply a random, secret token, that identifies an application in much the same way as a password identifies a user. The API key for an application can be retrieved in the Application view in the web interface, or using the get application API. The API key should be provided to the application in a secure manner.

If you retrieve an application’s API key in the web interface, it is already encoded in the proper form for passing as the Basic auth parameter when calling the create session API. If you retrieve the application credential directly using the get application API, the Basic authentication string is the Base64 encoding of the application ID and the application credential separated by a colon. For example, to authenticate as the application with ID 71faf7d9-d22f-464c-a5d1-db2afcd1936c and credential 4KvMN0wpOjVeecWf7_EuCqVIZUM9gFUYxRg3KfN_u8R-vXnw1RDA5z9TsmkEuOcGYUMP6t1xbAwf_ScbskjRRw, supply the following header with the create session request:

Authorization: Basic NzFmYWY3ZDktZDIyZi00NjRjLWE1ZDEtZGIyYWZjZDE5MzZjOjRLdk1OMHdwT2pWZWVjV2Y3X0V1Q3FWSVpVTTlnRlVZeFJnM0tmTl91OFItdlhudzFSREE1ejlUc21rRXVPY0dZVU1QNnQxeGJBd2ZfU2Nic2tqUlJ3

Regenerating an API key

You can regenerate an application’s API key by opening the application detail page, navigating to the Info tab, and clicking the Regenerate button in the API Key section. You can also regenerate an application’s API key on your account Application page. Note that regenerating an API key will terminate any existing sessions, and clients configured with the previous API key will no longer be able to communicate with SmartKey.

You can also regenerate an application’s API key on your account Application page. Note that regenerating an API key will terminate any existing sessions, and clients configured with the previous API key will no longer be able to communicate with SmartKey.

Application authentication using client certificates

Applications can also be authenticated by presenting a client certificate when establishing a TLS connection with SmartKey. The certificate associated with an application must be configured in SmartKey, either using the web interface, or by using the update application API.

When authenticating with a certificate, the HTTP Basic authentication string is the Base64 encoding of the application ID. Present both the certificate and the bearer token obtained from the create session API with each request.

Switching between API key and client certificate authentication

To change an application that is authenticating with an API key to authenticate with a client certificate, or vice-versa, open the application detail page, navigate to the Info tab, and open the “Change authentication method” drop-down. Select the desired authentication method and click Save. If switching to client certificate authentication, you will be prompted to upload a certificate.