Request for an access token
---------------------------

Endpoint:

	https://auth.iudx.org.in/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>		// required
			"token-time"		: <the time in seconds, till which the token should be valid>	// optional
		}

	2. complex:

		{
			"request" : {										// required
				"id"		: <a resource id for which access is requested>			// required
				"apis"		: <an array of APIs for which access is requested>		// optional
				"methods"	: <an array of methods a consumer wishes to call on the APIs>	// optional
				"body"		: <a dictionary of body variables to be called with the API>	// optional
			},

			"token-time"		: <the time in seconds, till which the token should be valid>	// optional
		}

	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.iudx.org.in/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.iudx.org.in/user@domain.com/2204adcbc990ffff234689aaabcdef90",
				"token-type"	: "IUDX",
				"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 IUDX token consist of 3 fields (delimited by '/'):

				1. Who has issued the token (The Auth server)
				2. To whom the token has been issued (The consumer)
				3. Random string

			In the above example:
				token = "auth.iudx.org.in/user@domain.com/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.iudx.org.in/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.iudx.org.in/user@domain.com/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.iudx.org.in/user@domain.com/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.iudx.org.in/token-introspect.html

	token revoke API:
		http://auth.iudx.org.in/token-revoke.html

	token revoke all API:
		http://auth.iudx.org.in/token-revoke-all.html