REST API Authentication

Authenticating against the REST API is done using Bearer authentication over HTTPS (SSL). The tokens are passed to the server as JSON Web tokens (JWT).

This article explains how to configure authentication and request an access token for machine-to-machine scenarios. If you are looking for a way to authenticate end-users in an API driven frontend setup, you should read the frontend authentication article which has more information on the subject.

Configuration

Before you can access the API you must configure a client Id and Secret for your app in appsettings.json. These values are just arbitrary strings but a good recommendation is that the Id should identify your application, e.g. the name or url of your application. The Secret is equivalent to a password and you should treat is as such by making sure it cannot be easily guessed and that you protect it from being exposed.

"Clients": [
    {
        Id: "your-client-id",
        Secret: "your-client-secret"
    }
]

Request a token

To obtain an access token you need to perform an OAuth 2 Client Credentials call to your Weavy backend as described below. The request should be made to the /api/auth token endpoint.

Transmit the following parameters in the request body using the application/x-www-form-urlencoded format:

  • grant_type - Value must be set to "client_credentials"
  • client_id - The client id as defined in your configuration settings
  • client_secret - The client secret as defined in your configuration settings

All successful auth requests will return an access token that gives the caller full access to Weavy so it is very important that the token is kept secure.

Example

The example below shows a complete auth request that returns an access token. Replace {client-id} and {client-secret} with your configured values.

Request

$ curl -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id={client-id}&client_secret={client-secret}' https://{your-weavy-url}/api/auth

Response

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJXZWF2eSIsInN1YiI6ImRlbW8iLCJjbGl...",
    "token_type": "Bearer",
    "expires_in": 3600
}
Weavy Docs