Authentication¶
APIs may require your application to authorize and authenticate. The widely-used OAuth 2.0 authorization framework is used. You can read more about OAuth 2.0 here or here. In short, with OAuth 2.0 you get an access token using an authorization grant and then use that access token when using the Spinque Query API.
Only members of the Spinque workspace that hosts the API are authorized to use that API. The workspace administrators can add or remove members.
Members of a workspace may include System-to-System accounts. These are accounts that can only be used by (trusted) application and cannot be used to sign in to Spinque Desk.
Grant types¶
A grant is a method to obtain an access token. The next section tells you how to use such an access token with the Spinque Query API.
All grants described at this Auth0 documentation page are available at login.spinque.com. This section highlights the two most-used grants: the Client Credentials grant and the Authorization Code with PKCE grant.
In general, server applications should use the Client Credential grant while browser applications should use the Authorization Code grant with PKCE.
Client Credentials grant¶
For server applications, CLIs, deamons, etc, this client credentials grant provides an easy and secure way to authenticate. A Client ID and Client Secret, which can be generated from Spinque Desk, are directly traded for a short-lived access token.
The Client Secret must always stay private so that’s why this flow is only available for trusted applications over which you have complete control and that run in a trusted environment, such as on your own servers. Authenticating browser applications should not be done with this grant but, for example, using the Authorization Code with PKCE grant.
Steps¶
Generate a Client ID and Client Secret for your application from Spinque Desk (Settings > Team Members > System-to-System account).
Your app authenticates with the Spinque Authorization server using the Client ID and Client Secret (/oauth/token endpoint). Also specify the grant type (‘client_credentials’) and audience (‘https://rest.spinque.com’).
The Spinque Authorization Server validates the Client ID and Client Secret.
The Spinque Authorization Server responds with an Access Token.
Your application can use the Access Token to call the Spinque Query API.
The API responds with requested search results.
Using cURL (replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET):
curl "https://login.spinque.com/oauth/token" -X POST -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials&audience=https://rest.spinque.com/"
Using Postman:
Create a new request for the Spinque Query API call you want to do, for example “https://rest.spinque.com/4/my-workspace/api/my-api/e/my-endpoint/results?config=default&count=30”.
Under “Authorization”, click the “Type” drop-down and select “OAuth 2.0”.
Make sure “Add authorization data to” is set to “Request Headers”.
To the right, scroll down to “Configure New Token”.
Under the “Configuration Options” tab, add a name for your new token. This can be anything you want.
For “Grant Type”, select “Client Credentials”.
For “Access Token URL”, fill in “https://login.spinque.com/oauth/token”.
Fill in your Client ID and Client Secret in the next two fields.
Leave the “Scope” empty.
Set “CLient Authentication” to “Send client credentials in body”.
Open the “Advanced Options” tab.
Set “Audience” to “https://rest.spinque.com/”.
Click on “Get New Access Token” and, if successfull, “Proceed” and then “Use Token”.
Now click “Send” to send the request to the Spinque Query API.
Authorization Code grant with Proof Key for Code Exchange (PKCE)¶
For applications whose source code is available or that can be decompiled, additional security measures must be taken.
The PKCE-enhanced Authorization Code grant introduces a secret created by the calling application that can be verified by the authorization server; this secret is called the Code Verifier. The calling app also creates a transform value of the Code Verifier called the Code Challenge and sends this value over HTTPS to retrieve an Authorization Code. This way, a malicious attacker can only intercept the Authorization Code, and they cannot exchange it for a token without the Code Verifier.
Please note: users of your application will be prompted to sign in with a Spinque-account. This Spinque-account must (at least) have the API-role in the workspace you want to access.
Steps¶
The user clicks Login within your application.
Your browser application generate a Code Verifier and from this generates a Code Challenge.
Your browser applicarion sends a Authorization Code request and the Code Challenge to the Spinque Authorization server (/authorize endpoint).
The Spinque Authorization server redirects the user to the login and authorization prompt.
The user authenticates using their Spinque-account and may see a consent page listing the permissions that will be given to the application.
The Spinque authorization server stores the Code Challenge and redirects the user back to your browser application with an Authorization Code, which is good for one use.
Your browser application sends this code and the Code Verifier (created in step 2) to the Spinque Authorization server (/oauth/token endpoint).
The Spinque Authorization server verifies the Code Challenge and Code Verifier.
The Spinque Authorization server responds with an ID Token and Access Token (and optionally, a Refresh Token).
Your browser application can use the Access Token to call the Spinque Query API to request search results.
Implementation¶
Implementing the Authorization Code flow with PKCE requires generating cryptographically-random strings and is more involved than other grants, such as the Client Credentials grant for server applications. The precise requirements can be found in the OAuth 2.0 RFC 7636 spec.
To ease this, it’s recommended you use a third-party library to handle most of the flow for you. Tried and tested with Spinque are:
The @spinque/query-api library for TypeScript/JavaScript includes support for this grant.
The @auth0/auth0-spa-js package is a SDK for Single Page Applications that supports this grant.
Access token¶
Authentication with the Spinque Query API is done using an access token. Access tokens are a short-lived pieces of evidence that you are authorized to use APIs within a workspace.
Simply add an Authorization header to the request with value Bearer YOUR_TOKEN, where YOUR_TOKEN is replaced by your access token.
Using cURL (replace YOUR_TOKEN):
curl "https://rest.spinque.com/4/my_workspace/api/my_api/e/my_endpoint/results?config=default" -H "Authorization: Bearer YOUR_TOKEN"
Access tokens are gained from the Spinque Authorization server at login.spinque.com. Any of the grants described in the next section can be used to gain an access token.