Request for an access token
---------------------------
Endpoint:
https://auth.datasetu.org/auth/v1/token
Description:
This API is used to request an access token from the Auth server.
The "token" can then be used to get data from a resource server.
Called by:
A "data consumer" with a valid class-2 or above certificate.
Methods:
POST
Headers:
content-type : "application/json"
Please note that "text/plain" can also be used to avoid CORS issues.
Body in JSON format:
There are two ways of giving inputs to this API:
1. simple:
{
"request" : <resource id(s) for which access is requested>
"token-time" : <the time in seconds, till which the token should be valid>
}
2. complex:
{
"request" : {
"id" : <a resource id for which access is requested>
"apis" : <an array of APIs for which access is requested>
"scopes" : <an array of scopesfor which access is requested>
"methods" : <an array of methods a consumer wishes to call on the APIs>
"methods" : <an array of methods a consumer wishes to call on the APIs>
"body" : <a dictionary of body variables to be called with the API>
},
"token-time" : <the time in seconds, till which the token should be valid>
}
Note:
The "request" field could also be an "array" of strings/objects.
The "request" fields are:
1. id:
The "id" is the identifer of the resource (a data-set) the consumer is interested in accessing.
Data consumers are not expected to create these "ids" themselves;
but are expected to get these "id"s from a catalogue server.
An example catalog server is: https://varanasi.iudx.org.in
And an example query to get ids is:
https://varanasi.iudx.org.in/catalogue/v1/search?item-type=resourceItem
The resource "id" consists of at least 4 parts seperated by a '/' indicating:
1. The email domain of the data provider.
2. SHA-1 hash of the data provider's email-id (to mask the provider's email).
3. The hostname (FQDN) of the resource server where the resource is hosted.
4. The name of the resource (which may contain additional '/'s).
For example:
"example.com/9cf2c2382cf661fc20a4776345a3be7a143a109c/rs.com/resource-name"
2. apis
The "apis" is the set of APIs a consumer wants to access on a "id".
Instead of "apis", just "api" (a string) could also be used.
For example: ["/latest", "/query"]
As the field is optional, the default value of "apis" is: ["/*"]
3. methods
The "methods" is the set of methods a consumer wants to access on an 'api'.
Instead of "methods", just "method" (a string) could also be used.
For example: ["GET", "POST"]
As the field is optional, the default value of "methods" is: ["*"]
4. body
The body indicates the JSON body to be passed with the "apis".
For example: {"operation" : "select", "on" : "all"}
As the field is optional, the default value of "body" is: null
HTTP response code:
200
If access is allowed.
403
If access is denied.
429
If the client makes too many requests.
Using pyIUDX SDK:
from pyIUDX.auth import auth
iudx_auth = auth.Auth("certificate.pem","private-key.pem")
request = [
"example.com/9cf2c2382cf661fc20a4776345a3be7a143a109c/rs.com/r1",
"example.com/5332dabcd033fffca0a3332abcdefe7a143a109c/rs.com/r2"
]
iudx_auth.get_token(request)
CURL examples:
1. Requesting token for data from a single resource server
Request:
curl -XPOST https://auth.datasetu.org/auth/v1/token
--cert certificate.pem --key private-key.pem
-H 'content-type: application/json'
-d '{
"request" : [
"example.com/9cf2c2382cf661fc20a4776345a3be7a143a109c/rs.com/r1",
"example.com/5332dabcd033fffca0a3332abcdefe7a143a109c/rs.com/r2"
]
}'
Response:
200 OK
content-type : "application/json"
{
"token" : "auth.datasetu.org/2204adcbc990ffff234689aaabcdef90",
"token-type" : "DATASETU",
"expires-in" : 3600,
"server-token" : {
"rs.com" : true
}
}
Response fields:
1. token
Is the access token required to access data from a resource server
("rs.com" in this case), and is in the format: 'auth-server/consumer/random-bytes'
A valid DataSetu token consist of 2 fields (delimited by '/'):
1. Who has issued the token (The Auth server)
2. Random string
In the above example:
token = "auth.datasetu.org/2204adcbc990ffff234689aaabcdef90"
2. expires-in
Indicates how long the token is valid in seconds.
3. server-token
This is the token for the resource server, it can be ignored
if request only contains "id"s from a single resource-server.
In the above example, there is only 1 resource-server : "rs.com".
2. Requesting token for data from multiple resource servers
Request:
curl -XPOST https://auth.datasetu.org/auth/v1/token
--cert certificate.pem --key private-key.pem
-H 'content-type: application/json'
-d '{
"request" : [
"example.com/9cf2c2382cf661fc20a4776345a3be7a143a109c/rs1.com/r1"
"example.com/9cf2c2382cf661fc20a4776345a3be7a143a109c/rs2.com/r2"
]
}'
Response:
200 OK
content-type : "application/json"
{
"token" : "auth.datasetu.org/1802a84d157ff4d113150aeca8bdacee",
"token-type" : "IUDX",
"expires-in" : 3600,
"server-token" : {
"rs1.com" : "rs1.com/91834abcd323924339ab",
"rs2.com" : "rs2.com/52338cdfff3222699900"
}
}
Other response fields:
3. server-token
The "server-token" field is meaningful if the request body
contains id's from multiple resource servers
In this example:
"rs1.com" and "rs2.com"
In the above example, when requesting data from a resource server,
the consumer must also provide the "server-token" of the respective resource server,
along with the consumer's "token".
In the above example:
token = "auth.datasetu.org/1802a84d157ff4d113150aeca8bdacee"
and the "server-token" when a consumer requests data from:
"rs1.com" is "rs1.com/91834abcd323924339ab",
and
"rs2.com" is "rs2.com/52338cdfff3222699900"
The "server-token" ensures that only a genuine resource server can access its token.
See also:
token introspect API:
http://auth.datasetu.org/token-introspect.html
token revoke API:
http://auth.datasetu.org/token-revoke.html
token revoke all API:
http://auth.datasetu.org/token-revoke-all.html