Citesphere uses provides OAuth2 for handling authentication and authorization. You can use any form of OAuth OAuth2 Client to get the token, which needs to be passed to other APIs as a header.
Get Access Token
| Status | ||||
|---|---|---|---|---|
|
POST /api/v1/oauth/tokenQuery Parameters
...
Name
...
Type
...
Description
...
client_id
...
string
...
Required. The client ID you received from Citesphere for your App.
...
client_secret
...
string
...
Required. The client secret you received from Citesphere for your App.
...
code
...
string
...
Required. The code you received as a response after the user gave the permission
...
redirect_uri
...
string
...
The URL of the application you configured in Citesphere
...
state
...
string
...
The unguessable random string you provided during the authorization step
...
grant_type
...
string
...
Use authorization_code for retrieving anaccess_token.
For a list of values, check https://auth0.com/docs/applications/application-grant-types
Response
| Code Block | ||
|---|---|---|
| ||
{
"access_token": "2c7c0f10-adf5-47d2-a931-caeea29464ed",
"token_type": "bearer",
"refresh_token": "0d06219a-1b49-4925-9220-ef3b9810f09d",
"expires_in": 406,
"scope": "read"
} |
...
expires_in specifies the number of seconds remaining for the access_token to expire.
...
You should use the access_token as the Bearer token header for accessing any resource.
Header Name -
AuthorizationHeader Value -
Bearer 2c7c0f10-adf5-47d2-a931-caeea29464ed
...
a token.
If you are developing an application and would like to use Citesphere to authenticate your users, please refer to Using Citesphere to Authenticate Users for Single Sign-On.
Creating an App
Any application that would like to use Citesphere for authentication and authorization first needs to be registered with Citesphere.
Login to Citesphere as admin.
Go to Apps and add a new app.
You should see a form like this:
Provide the requested information:
App Name: a descriptive name of the app to be registered (e.g. the name of the app such as “Vogon”).
Description: a short description of the apps (does not have to be longer than a sentence).
Application Type:
Apps need user information (Authorization Code): for any app that needs to authenticate specific users (e.g. if you want to use Citesphere for user authentication).
Apps do not need user information (Client Credentials): for any app that do not want to log in users but need a way to talk to Citesphere.
Redirect URL: a url to redirect to after Citesphere has processed a users authentication.
Click “Add”
You should see something like this:
Make sure to copy the client secret and keep it in a safe place. Once you navigate away from this page, there is no way to retrieve this information.
Regenerating Client Secrets
If for some reason you loose a client secret or you want to revoke access to the app using the current client id and secret, you can regenerate a client secret. To do this navigate to the page of the app in Citesphere and click “Regenerate Secret.” A new secret will be created and shown.
| Note |
|---|
Note that once you have regenerated a secret, any app that uses the old secret will not be able to use Citesphere’s API (including OAuth) any longer. |