Gatekeeper APIs

Welcome to the Gatekeeper API usage guide. You will be able to see how easy is it to program against it. All features are accessible via REST calls.

Discovery API

Performing a HTTP GET against the base URL returns the full REST API calls supported by Gatekeeper

cURL Example

curl -X GET localhost:8000/ --header "Content-Type:application/json"

Example Response


[
	{
		"metadata":
		{
			"source": "T-Nova-AuthZ-Service"
		},
		"info":
		[
			{
				"msg": "Welcome to the T-Nova-AuthZ-Service",
				"purpose": "REST API Usage Guide",
				"disclaimer": "It's not yet final!",
				"notice": "Headers and body formats are not defined here."
			}
		],
		"api":
		[
			{
				"uri": "/",
				"method": "GET",
				"purpose": "REST API Structure and Capability Discovery"
			},
			{
				"uri": "/admin/user/",
				"method": "GET",
				"purpose": "Admin API to get list of all users"
			},
			{
				"uri": "/admin/user/",
				"method": "POST",
				"purpose": "Create a new user"
			},
 			{
				"uri": "/admin/user/{user-id}",
				"method": "GET",
				"purpose": "Admin API to get detailed info of a particular user"
			},
 			{
				"uri": "/admin/user/{user-id}",
				"method": "PUT",
				"purpose": "Admin API to modify details of a particular user"
			},
			{
				"uri": "/admin/user/{user-id}",
				"method": "DELETE",
				"purpose": "Admin API to delete a particular user"
			},
			{
				"uri": "/token/",
				"method": "POST",
				"purpose": "API to request a new service token"
			},
			{
				"uri": "/token/{token-uuid}",
				"method": "GET",
				"purpose": "Get details of this token, lifetime, user or service id of the creator, etc."
			},
			{
				"uri": "/token/{token-uuid}",
				"method": "DELETE",
				"purpose": "Revoke or essentially delete an existing token."
			},
			{
				"uri": "/token/validate/{token-uuid}",
				"method": "GET",
				"purpose": "Validate a existing token, OK/Not-OK type status response"
			},
			{
				"uri": "/auth/{user-id}",
				"method": "GET",
				"purpose": "Authenticate an existing user. OK/Not-OK type response."
			},
			{
				"uri": "/admin/service/",
				"method": "GET",
				"purpose": "Lists all registered services."
			},
			{
				"uri": "/admin/service/",
				"method": "POST",
				"purpose": "Registers a new service with gatekeeper."
			}
		]
	}
]

Admin APIs

These APIs below are accessible only to an administrator user, use of these APIs by non-admin credentials will result in authorization error.

API Endpoint: /admin/user/

HTTP Method: GET

cURL Example
curl -X GET localhost:8000/admin/user/ --header "Content-Type:application/json" --header "X-Auth-Token:admin-user-token"
The admin-user-token used in the above call must be generated using the token generation API and using the admin credentials while doing so.
Example Response
If successful, the returned response will contain the list of users registered with Gatekeeper. 

{
  "metadata": {
    "source": "T-Nova-AuthZ-Service"
  },
  "info": [
    {
      "msg": "list of active users"
    }
  ],
  "userlist": [
    "piyush"
  ]
}
If the admin-user-token provided does not have proper authorization, or is expired, the following response will be returned: 

{
    "metadata":
    {
        "source": "T-Nova-AuthZ-Service"
    },
    "info":
    [
        {
            "msg": "Unauthorized Access."
        }
    ]
}

API Endpoint: /admin/user/

HTTP Method: POST

cURL Example
curl -X POST localhost:8000/admin/user/ --header "Content-Type:application/json" --header "X-Auth-Token:admin-user-token" -d '{"username":"someuser","password":"somepass","isadmin":"n", "accesslist":"comma separated service shortcodes"}'
The admin-user-token used in the above call must be generated using the token generation API and using the admin credentials while doing so. The comma separated service shortcodes specifies the list of services this user will be allowed access to. The service shortcode is the value specified while registering a service with Gatekeeper.
Example Response
If the user is registered successfully, the sample response will look as shown below. The response contains user-id which must be stored for later use. Also any modification to be made to this user's account need this id to construct the correct API endpoint. 

{
	"metadata":
	{
		"source": "T-Nova-AuthZ-Service"
	},
	"info":
	[
		{
			"msg": "user created successfully",
			"auth-uri": "/auth/{id}",
			"admin-uri": "/admin/user/{id}",
			"id": "{some-value}"
		}
	]
}
If the user already exists in the system, the call will fail with following response: 

{
	"metadata":
	{
		"source": "T-Nova-AuthZ-Service"
	},
	"info":
	[
		{
			"msg": "User already exists."
		}
	]
}

API Endpoint: /admin/user/{user-id}

HTTP Method: GET

cURL Example
curl -X GET localhost:8000/admin/user/2 --header "Content-Type:application/json" --header "X-Auth-Token:admin-user-token">
The admin-user-token used in the above call must be generated using the token generation API and using the admin credentials while doing so.
Example Response
If the user account exists, then the following sample response will be returned: 

{
	"metadata":
	{
		"source": "T-Nova-AuthZ-Service"
	},
	"info":
	[
		{
			"msg": "Account details.",
			"username": "some-user-name",
			"isadmin": "y/n",
			"capabilitylist": "comma separated list of service short-codes"
		}
	]
}
If the user account does not exist, then the following response will be returned: 

{
	"metadata":
	{
		"source": "T-Nova-AuthZ-Service"
	},
	"info":
	[
		{
			"msg": "User not found."
		}
	]
}

API Endpoint: /admin/user/{user-id}

HTTP Method: PUT

cURL Example
Any one of the following three variations could be used 

url -X PUT localhost:8000/admin/user/{id} --header "Content-Type:application/json" --header "X-Auth-Token:admin-user-token" -d '{"isadmin":"y"}'
url -X PUT localhost:8000/admin/user/{id} --header "Content-Type:application/json" --header "X-Auth-Token:admin-user-token" -d '{"accesslist":"servicex,servicey"}'
url -X PUT localhost:8000/admin/user/{id} --header "Content-Type:application/json" --header "X-Auth-Token:admin-user-token" -d '{"accesslist":"servicex,servicey","isadmin":"y"}'
The isadmin and accesslist fields contains the new values for the user account. The admin-user-token used in the above call must be generated using the token generation API and using the admin credentials while doing so.
Example Response
If the user account exists and the update was successful, then the following sample response will be returned: 

{
    "metadata":
    {
        "source": "T-Nova-AuthZ-Service"
    },
    "info":
    [
        {
            "msg": "Update Successful."
        }
    ]
}
If for some reason, update fails, the following response will be returned: 

{
	"metadata":
	{
		"source": "T-Nova-AuthZ-Service"
	},
	"info":
	[
		{
			"msg": "Update Failed."
		}
	]
}

API Endpoint: /auth/{user-id}

HTTP Method: GET

cURL Example
Simple authentication of an user could be performed as shown below: 
curl -X GET localhost:8000/auth/{id} --header "Content-Type:application/json" --header "X-Auth-Password:somepass"
It is important to note that username is not used in this request, instead the user-id is used. This is the same id which is returned in the response body of user registration process. If the authentication is successful, then the response returned is: 

{
    "metadata":
    {
        "source": "T-Nova-AuthZ-Service"
    },
    "info":
    [
        {
            "msg": "Authentication Successful."
        }
    ],
    "tokenlist":
    {
        "id":
		[
			"3E055F4B-B10F-40FF-9FCD-C55E3E94062B"
		],
        "valid-until":
		[
			"2015-06-17 18:53:06 +0200 CEST"
		]
    }
}
The response can contain list of active user tokens in response body. If the authentication failes, the following message is returned: 

{
	"metadata":
	{
		"source": "T-Nova-AuthZ-Service"
	},
	"info":
	[
		{
			"msg": "Incorrect Password."
		}
	]
}

API Endpoint: /token/

HTTP Method: POST

cURL Example
curl -X POST localhost:8000/token/ --header "Content-Type:application/json" --header "X-Auth-Password:somepass" --header "X-Auth-Uid:{id}"
The X-Auth-Uid value is the user-id which is returned when the user details were registered with Gatekeeper. If the password is correct, the call returns a new token along with the validity. If the user authentication is successful, the (example) response is: 

{
    "metadata":
    {
        "source": "T-Nova-AuthZ-Service"
    },
    "info":
    [
        {
            "msg": "Token Details."
        }
    ],
    "token":
    {
        "id":"13D707C4-BF77-4CE3-98D9-772D51A3BCC0",
        "valid-until":"2015-06-17 19:03:58.616306246 +0200 CEST"
    }
}
And if the authentication fails, the API returns: 

{
	"metadata":
	{
		"source": "T-Nova-AuthZ-Service"
	},
	"info":
	[
		{
			"msg": "Incorrect Password."
		}
	]
}

API Endpoint: /token/validate/{token-uuid}

HTTP Method: GET

cURL Example

curl -X GET localhost:8000/token/validate/{token-uuid} --header "Content-Type:application/json" --header "X-Auth-Uid:{id}"
curl -X GET localhost:8000/token/validate/{token-uuid} --header "Content-Type:application/json" --header "X-Auth-Service-Key:{service-key}"
This API can be used by the user or user-proxy process to validate an existing token, or it can be used by a service (the service should be already registered with Gatekeeper) to perform authorization check for a user against the presented token. The token-uuid is the token that has to be validated, and id is the user-id. If a registered service makes the API call, the service-key is the unique key associated with a particular service by Gatekeeper. If the validation / authorization of the token is successful, the following response is returned: 

{
   "metadata":
   {
       "source": "T-Nova-AuthZ-Service"
   },
   "info":
   [
        {
           "msg": "Validation / Authorization Successful."
       }
   ]
}
In case the validation / authorization fails, the following response is returned. 

{
   "metadata":
   {
       "source": "T-Nova-AuthZ-Service"
   },
   "info":
   [
       {
           "msg": "Validation / Authorization Failed."
       }
   ]
}

Credits

Development Team