Overview
For authentication use OAuth 2.0 bearer access token in the HTTP headers of every request. Obtain a bearer token using your client id and client secret using the login endpoint. After the session, we also recommend using the logout endpoint to log out of the session. The default timeout for the bearer token is 1 hour, after which an UNAUTHORIZED (401) status code will be returned, at which point you will need again obtain a new bearer access token using "login" command.
Typical workflow:
- Obtain access token via login endpoint, keep the resulting bearer token in memory
- Use the appropriate API endpoints as needed, passing in bearer token.
- Call logout after use.
Login
To get bearer access token, turn on Management API in the User settings to obtain your "client id" and "client secret". Be sure to keep this in the safe place.
Query
POST /api/1.0/login
Parameter | Comments |
---|---|
client_id | client_id is a part of credentials obtained from User settings. |
client_secret | client_secret is a part of credentials obtained from User settings. |
Response
HTTP Status | Response |
---|---|
200 OK |
{ "access_token": <Access Token used for API calls>, "token_type": <Type of Token> ("Bearer" always), "expires_in": <Number of seconds before the token expires> (by default - 3600 seconds) } |
400 BAD_REQUEST |
{ "message": <Error details>, "documentation_url": <Documentation link> } Error details:
|
404 NOT_FOUND |
{ "message": <Error details>, "documentation_url": <Documentation link> } Error details:
|
Bearer access token
The returned by "login" bearer access token should be used in subsequent calls to the Management API in the header named "Authorization":
Authorization: Bearer 69EuuRHieoidfbth48ygR9843wrgw94930g39845
Example
curl POST -i -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
https://www.knowi.com/api/1.0/login
Logout
Call this endpoint to destroy the bearer token. You can re-issue a bearer token using the login endpoint.
Query
DELETE /api/1.0/logout
No parameters |
---|
Response
HTTP Status | Response |
---|---|
200 OK | No response body |
400 BAD_REQUEST |
{ "message": <Error details>, "documentation_url": <Documentation link> } Common error details:
|
401 UNAUTHORIZED |
{ "message": <Error details>, "documentation_url": <Documentation link> } Common error details:
|
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE
https://www.knowi.com/api/1.0/logout