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 settingsclient_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
}