Geni Platform uses the OAuth 2.0 protocol for authentication and authorization.
The Platform supports a number of different flows that you can use within your website, desktop and mobile applications.
Authenticaton/Authorization Flows
The following table outlines the various mechanisms Geni Platform uses to support each of those flows.
| Flow Name |
OAuth 2.0 Specification |
Description |
|
Server Side Flow
|
Authentication Code
|
Use this flow if your application needs to call Geni's API from the server side
|
|
Client Side Flow
|
Implicit Grant
|
Use this flow if your application needs to call Geni's API from a client, such as JavaScript in a Web browser or from a native mobile or desktop application.
|
|
Desktop App Flow
|
Implicit Grant
|
Customized version of the Client Side Flow targeted for Desktop applications.
|
|
Mobile App Flow
|
Implicit Grant
|
Customized version of the Client Side Flow targeted for Mobile applications.
|
|
Trusted App Flow
|
Resource Owner Password Credentials
|
Use this flow only if your application has a trust relationship with the user and no other flow can work for your application. For example, if you have a highly privileged desktop application and user wants to give your application explicit access to the user data.
This flow is not enabled by default. If you want to use this flow, please email us and after we review your application we will make a decision on granting you the flow access.
|
|
App Login Flow
|
Client Credentials
|
Use this flow if your application needs to retrieve public data or take adminstrative actions.
The calls will not be made on behalf of the user, but on behalf of the app itself.
Unlike public api calls without a token, this flow has a higher rate limit.
|
Authorization Request
Authorization process uses web interface that allows users to login to the site and authorize your application to have access to their data.
Request URL
https://www.geni.com/platform/oauth/authorize
Parameters
|
Name
|
Description
|
Required
|
|
client_id
|
Application key (or id) is generated during the application registration.
|
Required for all flows
|
|
redirect_uri
|
URL that the user's browser will be redirected to once the application authorization is complete.
You can specify this URL in your application settings as a Callback URL, or pass it as a request paremeter.
The redirect_uri must be within the same domain as the Site Domain you specified in the application settings.
|
Required for all flows
|
|
response_type
|
Available options: code, token.
Default: code
|
false
|
|
scope
|
A comma delimited list of permissions that the application needs.
By default the scope is set to a full data access.
|
false
|
|
display
|
Provides a mechanism to select an appropriate template to display the authorization flow.
Available options: web, mobile, desktop, iframe.
Default: web
|
false
|
|
state
|
Used for additional parameters and CSRF protection.
|
false
|
Example
https://www.geni.com/platform/oauth/authorize?client_id=YOUR_APP_KEY&redirect_uri=YOUR_URL
Returned Fields
Return fields will vary based on the flow and the request parameters you pass in.
See the flow you are interested in for more information.
Request Token API
Request token API is used to exchange athorization code or a refresh token for a valid access token.
Depending on the flow you chose, you will have different options for calling this API.
This API will always return results encoded in JSON format.
End Point
https://www.geni.com/platform/oauth/request_token
Parameters
|
Name
|
Description
|
Required
|
|
client_id
|
Application key (or id) is generated during the app registration.
|
Required for all flows
|
|
client_secret
|
Application secret generated during the registration process and availble in the application settings.
The app secret should never be shared with anyone or embedded in any code that you will distribute (you should use the client-side flow for these scenarios).
|
Required for certain flows
|
|
redirect_uri
|
URL that was used to get the authorization code.
The redirect_uri must be within the same domain as the Site Domain you specify in the application settings.
|
Required for certain flows
|
|
grant_type
|
Available options: authorization_code, password, refresh_token.
For the server side flow the response type is defaulted to "authorization_code".
|
true
|
There are additional parameters based on the flow and the grant_type value.
Returned Fields
Return fields will vary based on the flow and the request parameters.
See the flow you are interested in from the list above.
Validate Token API
Verifies whether the token is valid.
End Point
https://www.geni.com/platform/oauth/validate_token
Parameters
|
Name
|
Description
|
Required
|
|
access_token
|
Access token to be validated.
|
true
|
Returned Fields
Returns a flag that indicates whether the token is valid or not.
Invalidate Token API
Invalidates the token.
End Point
https://www.geni.com/platform/oauth/invalidate_token
Parameters
|
Name
|
Description
|
Required
|
|
access_token
|
Access token to be invalidated.
|
true
|
Returned Fields
Returns a flag that indicates whether the token was invalidated.
