#OAuth Authorization Workflow
This guide will show you how to authorize your web application using OAuth2 and how to use the Fénix API so you can access Fénix users' information with their authorization.
##Table of Contents
- 1. Register Application
- 2. Request User Permission
- 3. Request the Access Token
- 4. Make an API request
- 5. Refreshing the access token
#1. Register Application
This section will explain how to register your application in Fénix.
-
Login at Fénix and select
Personal
->Manage Applications
. If it is not present, please contact support so you can get the roleDEVELOPER
. -
Select
Create Application
-
Fill the requested fields
- Logo - should be an image with 64x64 pixels
- Name - Application Name
- Description - Short text about your application
- Site URL - The application site with information about your application (optional, not to be confused with Redirect URL)
- Scopes - The scopes your application needs to request the users authorization
- Redirect URL - The endpoint in your application to proceed the OAuth2 flow.
After completing this registration process, you are ready to start the authorization workflow.
#2. Request User Permission
This section will explain how you can request the user permission so your application can access the Fénix API.
-
Your application must redirect the user to the following URL
https://fenix.ist.utl.pt/oauth/userdialog?client_id=<client_id>&redirect_uri=<redirect_uri>
- You should get the
client_id
andredirect_uri
values from the application details in Fénix.
- You should get the
The user will be redirected to a web page where it will be requested to authorize your application to access the scopes you selected in the application creation process. It will request user login if necessary.
##Error Handling If the user denies the authorization request the user will be redirected to
<redirect_uri>?error=access_denied&error_description=User didn't allow the application
At this point you can't continue the authorization workflow.
#3. Request the Access Token
If the user authorizes your application, the web browser will be redirected to the redirect_uri
like this
<redirect_uri>?code=XXXXXXXXXXX
At this point you must issue a POST
request on
https://fenix.ist.utl.pt/oauth/access_token?client_id=<client_id>&client_secret=<client_secret>&redirect_uri=<redirect_uri>&code=<code>&grant_type=authorization_code
- The
client_id
,redirect_uri
,client_secret
can be found the on the application details in Fénix. - The
code
is passed as a parameter toredirect_uri
where the current request must be made.
If everything goes smoothly, you should get an application/json
200 OK response with the following format
{"access_token":"IGNhbiBjb252ZXJ0IHRleHRzIHVzaW5nIHNldmVyYWwgY29kZSBwYWdlcyAodXNpbmcgQ2hhclNl", "refresh_token":"dCBwcm9wZXJ0eSkgZnJvbSBVbmljb2RlIHN0cmluZyB0byBieXRlIGFycmF5IGFuZCB0aGVuIGNv", expires:"3600"}
##Error Handling
If something goes wrong a application/json
400 BAD_REQUEST
response will be issued in this format:
{"error":"invalid_grant","error_description":"..."}
The following descriptions can occur:
Client ID not recognized
- when the client id is not found (please check the application details)Credentials or redirect_uri don't match
- When theclient_secret
is wrong or theredirect_uri
is not the same that is registeredCode Invalid
- thecode
is no longer validCode expired
- thecode
has expired
#4. Make an API request
At this point you already have an access_token
and you want to invoke the Fénix API on behalf of the user who previously gave your application permissions.
The API documentation is described here
The API base URL is https://fenix.ist.utl.pt/api/v1
Each endpoint belongs to a scope except the endpoints that are public.
When requesting a scoped endpoint the query param access_token
must be present in the URL. For example:
https://fenix.ist.utl.pt/api/v1/person?access_token=<access_token>
##Error Handling
If something goes wrong a application/json
HTTP 401 Not Authorized
response will be issued in this forma
t:
{"error":"...","error_description":"..."}
The error
can be one of the following
invalidScope
- Application doesn't have permissions to this endpoint.accessTokenInvalid
- Access Token doesn't match.accessTokenExpired
- The access has expired. Please use the refresh token endpoint to generate a new one.accessTokenInvalidFormat
- Access Token not recognized.
#5. Refreshing the access token
If the access_token
expires, the refresh_token
must used to get a new one. The refresh_token
never expires.
To get a new access_token
you must do a POST
request on :
https://fenix.ist.utl.pt/oauth/refresh_token?client_id=<client_id>&client_secret=<client_secret>&refresh_token=<refresh_token>
If everything goes smoothly, you should get an application/json
200 OK response with the following format
{"access_token":"IGNhbiBjb252ZXJ0IHRleHRzIHVzaW5nIHNldmVyYWwgY29kZSBwYWdlcyAodXNpbmcgQ2hhclNl", "expires":"3600"}
##Error Handling
If something goes wrong a application/json
HTTP 401 Not Authorized
response will be issued in this forma
t:
{"error":"...","error_description":"..."}
The error
can be one of the following
invalid_grant
- Credentials or redirect_uri don't matchrefreshTokenInvalid
- Refresh token doesn't matchrefreshTokenInvalidFormat
- Refresh Token not recognized.