Configure an API

To be able to protect an API, you need to configure two parts of the Authway service. Step 1 is to define an API scope and with that in place, step 2 is to define an API resource.

Configure an API Scope

A scope defines a logical API where you want to be able to give one or more clients the opportunity to use that API. This means that an application that wants to be able to call the API must request the scope when the token is requested at sign-in. This logical API can have one or more implementations (API resources), but usually a logical API is implemented by an API resource. For Authway, the scope needs to be defined in the same way in both test and production environments.

The naming of a scope should be lowercase (just as the standard identity scopes are) and if you want to distinguish between words, use a “_” between each word. For example Authway API scope is called “idp_auth_api”.

For an API scope, you specify all the claims that the API needs to be able to function, ie what information from the API needs the API to function properly.

There are possible situations for defining several API ranges to one API, such as that one would like to differentiate between a scope that only gives the client access to GET operations (read) and have another scope for the client to use PUT/POST/DELETE operations (updates). Our experience is that it should rarely be controlled per client, but rather by the user’s permissions (ie the user’s access to functionality). In general, we therefore recommend that you use a single API scope for your entire API (GET/PUT/POST/DELETE).

We recommend that an API Scope is associated with a module, so that the administration of External Systems automatically is assigned correct scopes.

Configure an API Resource

An API resource represents an implementation of an API scope. The API resource has a configuration for the site where the API is distributed too, which means that if several distributions of the API is made to different websites (addresses), several API resources should be configured. For the API resource, you specify which API scope the API implements.

We recommend that the API resource is given the same name as the API scope, and if this is done, the API scope is automatically connected to the resource when it is created. This can also be done manually, e.g. if the API implements more than one scope.

Secrets for an API Resource

If the API resource should be able to use OAuth/OpenId Connect APIs that are protected, a secret is required (corresponding to a user’s password). Examples of such use cases are is to use introspection to support reference tokens along with access tokens.

This secret can be created and administered on the “Secrets” tab of the API resource. When a new secret is created, it is displayed directly in the user interface and then it is important that it is copied and stored securely for the API. Authway will not be able to show the value of the secret again (in the same way that passwords cannot be displayed). This means that if the secret is lost, a new secret must be created. When a new secret is created, the old secret should be deleted or given an expiration date. The latter should be used if you want to change your secret in a controlled manner without getting any interruption.