Skip to main content

Securing APIs

There are two types of APIs in RAW:

  • public APIs, which can be accessed by anyone in the public, without having to be authenticated or authorized;
  • private APIs, which required the user to be authenticated and authorized.

Public APIs

To declare a public API, add the following definition to the endpoint YAML file:

security:
public: true

A public endpoint can be access by anyone without any authentication or authorization.

For more information on the endpoint YAML definition, consult our reference guide.

Attention

Public APIs should be used carefully as any execution costs will be incurred on your account.

Private APIs

To declare a private API, add the following definition to the endpoint YAML file:

security:
public: false

This is the default in case the security section is not included.

A private endpoint can only be accessed by members of the organization. Therefore, a valid OAuth access token must be included in the HTTP request.

In addition, private endpoints can have additional authorization restrictions in the form of scopes. Scopes are a list of strings included in the OAuth access token. Only tokens containing those scopes are authorized to access the endpoint.

For instance, assume an endpoint defined as:

security:
public: false
scopes:
- department_head
- hr

This endpoint can only be accessed by users or applications whose scopes include 'department_head' and 'hr'. All other users will not be authorized to access the endpoint.

In order for your clients to be able to execute a private endpoint, you can provide them with an API key that is associated to at least one scope that your endpoint has defined.

For more information on the endpoint YAML definition, consult our Endpoint configuration guide.

For more information on the endpoint protocol, consult our protocol guide.

Accessing User Scopes in RQL

Scopes Keyword

Its possible to access user-scopes in RQL using the predefined variable scopes. This is a list of strings and corresponds to the scopes/permissions of the user calling the endpoint.

For example the following function will return a different output depending if the user calling it has the scope "special" in his permissions.

Function querying scopes
special() := {
if ("special" in scopes) "you are special"
else "you are not special"
}