Authentication and Status Codes¶
Status Codes¶
200 - Successful [
GET
,PATCH
,PUT
]201 - Resource successfully created [
POST
]204 - Resouce successfully deleted [
DELETE
]403 - Permission denied to resource
404 - Resource was not found
Request based Authentication¶
Ona JSON API enpoints support both Basic authentication and API Token
Authentication through the Authorization
header.
Basic Authentication¶
Example using curl:
curl -X GET https://api.ona.io/api/v1/ -u username:password
Token Authentication¶
Example using curl:
curl -X GET https://api.ona.io/api/v1/ -H "Authorization: Token TOKEN_KEY"
Temporary Token Authentication¶
Example using curl:
curl -X GET https://api.ona.io/api/v1/ -H "Authorization: TempToken TOKEN_KEY"
The temporary token expires after DEFAULT_TEMP_TOKEN_EXPIRY_TIME
seconds,
which defaults to 21600 seconds (6 hours). To expire the temporary token manually
use the /user/expire endpoint. Example using curl and password authentication:
curl -X DELETE http://api.ona.io/api/v1/user/expire -u username:password
You could use another type of authentication as well.
To activate authentication via temporary token you must add the TemporaryToken class to your local_settings.py file, for example:
- ::
- REST_FRAMEWORK[‘DEFAULT_AUTHENTICATION_CLASSES’] = (
‘onadata.libs.authentication.DigestAuthentication’, ‘onadata.libs.authentication.TempTokenAuthentication’, …
Using Oauth2 with the Ona API¶
You can learn more about oauth2 `here`_.
1. Register your client application with Ona - register¶
name
- name of your applicationclient_type
- Client Type: select confidentialauthorization_grant_type
- Authorization grant type: Authorization coderedirect_uri
- Redirect urls: redirection endpoint
Keep note of the client_id
and the client_secret
, it is required
when requesting for an access_token
.
3. Request for access token.¶
You need to make a POST
request with grant_type
, code
,
client_id
and redirect_uri
as POST
payload params. You
should authenticate the request with Basic Authentication
using your
client_id
and client_secret
as username:password
pair.
Request:
POST/o/token
Payload:
grant_type=authorization_code&code=YYYYYYYYY&client_id=XXXXXX&redirect_uri=http://redirect/uri/path
curl example:
curl -X POST -d "grant_type=authorization_code&
code=PSwrMilnJESZVFfFsyEmEukNv0sGZ8&
client_id=e8x4zzJJIyOikDqjPcsCJrmnU22QbpfHQo4HhRnv&
redirect_uri=http://localhost:30000" "http://api.ona.io/o/token/"
--user "e8:xo7i4LNpMj"
Response:
{
"access_token": "Q6dJBs9Vkf7a2lVI7NKLT8F7c6DfLD",
"token_type": "Bearer", "expires_in": 36000,
"refresh_token": "53yF3uz79K1fif2TPtNBUFJSFhgnpE",
"scope": "read write groups"
}
Where:
access_token
- access token - expiresrefresh_token
- token to use to request a newaccess_token
in case it has expired.
Now that you have an access_token
you can make API calls.
4. Accessing the Ona API using the access_token
.¶
Example using curl:
curl -X GET https://api.ona.io/api/v1 -H "Authorization: Bearer ACCESS_TOKEN"
Making CORS - Cross-Origin Resource Sharing - requests to the Ona API¶
To find out more about CORS, you can read about it here. The following is a javascript code snippet on how to make a CORS request.
var xhr = new XMLHttpRequest();
xhr.withCredentials = false;
xhr.open('GET', 'https://api.ona.io/api/v1/user', true);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.setRequestHeader('Authorization', 'Token TOKEN_KEY');
xhr.send();
The following is a jquery code snippet on how to make a CORS request.
$.ajax({
method: "GET",
url: 'https://api.ona.io/api/v1/user',
dataType: 'json',
xhrFields: {
withCredentials: false
},
headers: {
'Authorization': 'Token TOKEN_KEY'
},
});
OpenID Connect Authentication¶
open-id-connect