Assign access levels to an API endpoint

Authorisation helps secure APIs by ensuring users or systems can only access what they have been explicitly permitted.

In your OpenAPI Specification (OAS), you define the security mechanisms for your API. For authorisation, this involves specifying the access levels and OAuth flows for each endpoint.

What are access levels?

An access level determines the level of authorisation needed to access a specific part of the API. Each access level offers a different degree of control. Within the same API, you can assign different access levels to different endpoints.

The API Platform supports application-restricted and user-restricted access levels.

For security reasons, avoid creating new open-access APIs. Direct any queries to the API Platform team.

Application-restricted endpoints are accessed using a client credentials flow. The application authenticates using its own credentials rather than on behalf of a user. Use this access level for server-to-server integrations where no user interaction is required.

Assign access levels to your API

Specify the access level for each endpoint in your application.yaml file by adding a security line that references the security schemes defined in your API documentation.

For application-restricted endpoints:

security:
  - applicationRestricted:

For user-restricted endpoints:

security:
  - userRestricted:

Set the security requirement

Unlike OpenAPI, the API Platform does not support multiple security requirements or multiple scopes per endpoint.

For userRestricted endpoints, a scope is mandatory. In the example below, hello is the scope:

paths:
  /somepath:
    get:
      ...
      security:
        - userRestricted:
          - hello

For applicationRestricted endpoints, a scope is optional and rarely used:

paths:
  /somepath:
    get:
      ...
      security:
        - applicationRestricted: []

Do not define an explicit authorization header. It is automatically inferred from the OAuth security scheme details.

Need support? If you are blocked at any step, contact your support route for help.

Got feedback? We are always improving this guidance. Share feedback to help improve the documentation.