Authentication with Geni

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.

rails-1a-012