API and Access keys as a service

Authress provider API Access Keys for your application or platform as a service. You can use the Authress generated Service Clients as API keys you give to your users and customers. This enables Authress to be used to verify and protect your APIs without having to write anything additional to generate, maintain, or secure these keys. If you are already using Authress, this feature comes for free out of the box.

This article provides a deeper dive into how these Service Client access keys work, and how to effectively use them. As we know from the service client KB article, there are a number of different scenarios where API keys or access keys are necessary. Included in the article is also how to assign permissions and access control for those service clients.

Here we'll discuss the flow as well as how Authress generates the access keys that you and your customers use to authenticate.

Generating service client JWTs

Either you are generating service clients and access keys for inter-service communication, or generating API keys for your users to access your service's APIs. We'll use Service Client or API Key interchangeably below. Specifically:

• Service Client is the service
• API Key is the key the service client uses to identify itself.

In the case you are providing a library or a CLI, the service client would be the developer or user, and they would pass the api key to the library or CLI at runtime.

Authress uses asymmetric access keys which are a Public/Private pair. The Public key lives in Authress and the Private key is generated and sent to the User or Developer for embedding in their service. Authress uses as asymmetric signatures because they are much more secure than a shared secret. For the generation of access keys for your users:

1. The user authenticates into your service using their identity provider
   • In the case you are using Authress they would use their SSO identity
2. After logging in, you would know which customer account they have access to
3. The user would use your portal to request a new api key
   • On request your service would make an API call to Authress to generate a Service Client and an associated access key
4. Return the access key back to the user
5. The user would embed the access key in your SDK to make calls to your API

How it works in Authress

The first interaction with Authress is the generation of the public/private key pair. When generated, the public key in stored in the Authress database, and the private key is returned to the user. The user takes their private key and stores it on their side. Authress recommends encrypting all secrets, and provides this AWS encryption example as a recommendation for how to do that.

Then later the service client uses the private key to create a JWT that can be passed back to API and can be verified against the public key JWK that was created in the first step. The JWT will be passed through your SDK to your API, verified and then sent to Authress for an authorization access check.

note

When the access token expires the client can generate a new JWT, and the Authress SDKs do this automatically. This avoids all the issues that are generated by using the common flat api key as well as increases security for both the application API as well as the client caller.

Building a client SDK

Because you'll be giving your users the access key generated by Authress, you'll need a way to generate JWTs from this access key. The easiest way to do this to embed the Authress SDK in your distributed SDK, because it already supports Private key => JWT creation. Here is an example snippet to place directly in your distributed SDKs, one exists for every language we support.

(Other SDKs are available in all the other languages on the Authress API documentation page)

note

In some cases, providing your users with an SDK isn't an option and in these situations, see the guidance regarding static private key usage.

Install Authress SDK (nodejs)

npm install @authress/sdk

Your client SDK (or CLI)

import { ServiceClientTokenProvider } from '@authress/sdk';

// Configure the custom domain: https://authress.io/app/#/settings?focus=domain
const authressCustomDomainUrl = 'https://auth.yourdomain.com';

class myApplicationServiceClient {
  async sdkApiCall() {
    // The customersSecretAccessToken is the private key you generated from Authress
    // to give to your customer as an API key.
    // Generate these by creating a service client and access key at:
    // https://authress.io/app/#/api?route=post-/v1/clients/-clientId-/access-keys
    const tokenProvider = new ServiceClientTokenProvider(
      customersSecretAccessToken, authressCustomDomainUrl);

    const token = await tokenProvider.getToken();
    const headers = { Authorization: `Bearer ${token}` };
    return httpClient.get(url, headers);
  }
}

Static key usage

caution

In most circumstances Authress recommends against exposing the private access key outside of the service's production runtime. The fewer places the key is exposed to the fewer opportunities it has to be compromised. When possible use one of the Authress SDKs to convert the secret access key to a JWT, otherwise please use the static secret access key and private key with care.

It isn't always the case that you can pass the API Access key to one of our SDKs to generate the necessary JWT. There are two situations where that frequently happens:

• OAuth delegation / authentication / token requests
• SaaS provider integrations

With these flows, usually a static secret string will have to be passed to the provider or process and that needs to work. For that reason the secret access keys generated by Authress actually provide this as well. By generating a secret access key for a service client, the access key can be used as a Bearer token in the Authorization header requests.

Your users would use the static secret in your SDK or a curl call to interact with your API:

Using the static service client access key directly

curl https://application.yourdomain.com -H"Authorization: Bearer sc_aaa.acc_001.secret"

Then on your service side you would need to verify the incoming secret. This would automatically get verified when passed to Authress, or it can be verified directly using one of the Authress SDKs:

[Application Service] Verify incoming tokens

import { AuthressClient } from '@authress/sdk';
const authressClient = new AuthressClient({ authressApiUrl: 'https://auth.yourdomain.com' });

try {
  // Grab authorization cookie from the request the best way to do this will be framework specific
  const userToken = request.headers.Authorization.split(' ')[1];
  const userIdentity = await authressClient.verifyToken(userToken);
} catch (error) {
  console.log('User is unauthorized', error);
  return { statusCode: 401 };
}

Or if you wish to verify Authress service client access keys without using the SDK, check out the Authress implementation of x25519 keys.