API Scopes

API Scopes

As an API developer, you need to:

1. Decide which information you would like applications to be able to access on a user's behalf.

2. Define these access levels as custom scopes. (To learn what scopes are, read Scopes.)

3. Identify these scopes so that calling applications can use them.

Ways to Use API Scopes

You can use API scopes in different ways:

• Third-Party Application: In this case, the calling application will request authorization from the user to access the requested scopes, and the user will approve or deny the request.

• First-Party Application: Applications registered under the same Login 3.0 domain as the API it is calling. By default, user consent is not requested, but you may configure consent to be required.

• Back-End Service: In scenarios where no user exists, consent is never requested.

All these examples use scopes to limit access through the use of a token. If desired, your API may also use additional logic beyond the token to enforce more extensive access control.

Example: An API Called by a Third-Party Application

Imagine you are building an API that provides bank account information to online payment applications. At various times, apps may need to read account balances or transfer funds. To do this, you create two scopes for your API:

• read:balance: Authorizes read access to an account balance.

• transfer:funds: Authorizes fund transfers.

A calling application will request authorization from the user to access the requested scopes, and the user will approve or deny the request. For example:

• The app may request read access by including the read:balance scope in its request.

• It may request access to make fund transfers by including the transfer:funds scope.

• It may request both scopes to access the user’s balance and transfer funds.

The app’s token will verify which scopes the user approved, and your API should respect those approved scopes.

Example: An API Called by a First-Party Application

Imagine building an API that provides data to an events application that you also created. You implement role-based access control (RBAC) and create roles:

• Organizer: Needs to create and update events.

• Participant: Needs to view and register for events.

You create scopes for your API:

• create:events: Authorizes creating events.

• update:events: Authorizes updating events.

• view:events: Authorizes read-only access for events.

• register:events: Authorizes registering for events.

Both your API and event application are registered with Login 3.0. User A (an organizer) is granted the create:events and update:events scopes, while User B (a participant) is granted the view:events and register:events scopes.

When User A authenticates, the application requests necessary scopes. No consent is requested since it is a first-party application. User A is only granted the create:events and update:events scopes based on their role.

Example: An API Called by a Back-End Service

Imagine working for a hospital with an API that produces imaging data for MRIs. The hospital has a service that copies imaging data to offsite storage and deletes local data after six months. You create scopes for your API:

• read:images: Authorizes read access to imaging data.

• delete:images: Authorizes delete access to imaging data.

The calling automated service requests the necessary scopes without user consent. It may:

• Request read access with the read:images scope.

• Request delete access with the delete:images scope.

• Request both scopes for read and delete access.

The automated service’s token verifies authorization for the requested scopes.