Rest API Authentication

The Weavy REST API uses token based authentication. Tokens are issued by the Weavy instance. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail unless specifically stated.

Authentication Clients

Weavy uses authentication clients to validate requests to the API. Clients are created and updated in the Weavy UI. Clients hold the information you need to make request for the API, namely the ClientId and the ClientSecret.

The client id and secret should be kept secure! Do not share the information in publicly accessible areas such as GitHub, client-side code, etc.

Manage Clients

To manage Authentication Clients, you need to sign in to the Weavy installation with an administrator account. Then navigate to https://{your-weavy-url}/manage/clients.

To add a new client, click the plus icon and specify Display Name, Client Id and Client Secret. It is possible to add multiple clients to facilitate different scenarios.

From the manage section it is also possible to disable and trash existing clients. Disabled or trashed clients cannot be used to authenticate API requests..

Authenticate using a Client

Authentication is done using the OAuth Client Credentials Flow.

When authenticating the following is happening:

  1. A caller authenticates with the https://{your-weavy-url}/api/auth token endpoint of the Weavy server using Client Id and Client Secret.
  2. Weavy validates the Client Id and Client Secret.
  3. Weavy responds with an access token.
  4. The caller can use the access token to call API endpoints.

Code samples

Request an access token:

curl -d "client_id={your-client-id}&client_secret={your-client-secret}&grant_type=client_credentials" https://{your-weavy-url}/api/auth

Response from token endpoint:

{
    "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi...",
    "token_type":"bearer",
    "expires_in":3600
}

Call the API using the access_token in the Authorization header:

curl -H "Accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi..." https://{your-weavy-url}/api/{api-endpoint}