OAuth2 Workflow

Using OAuth2 at a base level with the GitShare API for those new to OAuth.

OAuth2 Authentication

OAuth authentication is useful when you are writing a service that you want to make available to other GitShare users. OAuth allows you to register your application with GitShare. Once you register, you obtain a client access token that can be used to ask a GitShare user for access to their account. Once access is granted, you can call the GitShare API on behalf of that user, to read and write their files or to perform any action that user can perform. OAuth allows you to interact with someone else's account.

This is useful when...

  • you want to extend GitShare in some way.
  • you are building a service, and want your users to "bring their own storage" with them.
  • you want to give your users many storage platforms to choose between when importing or exporting data.

To get started with OAuth2, register your application.

Not Using Our SDK

This article is written for users that are not using one of the current SDKs. When using one of our SDKs, the correct fields and values should automatically be sent. The SDK will also store tokens/secrets and includes those with calls to the API.

1. Register Your Application

The first step is to register your application.

This will yield your Client Id and Client Secret. These will be used throughout the OAuth process and you should save these in your application.

2. Generate Authorization Url

To generate the authorization url, you will concatenate the base url and your client id returned from the call in step 1.

Example Authorization Url: https://<domain>/ oauth2/authorize/?client_id=CLIENT_ID&response_type=code&redirect_uri=REDIRECT_URI

Send your user to the authorization url. The user will allow or dissallow your application. If allowed and you have specified a callback url, the verifier will be sent to your application. If approved and you have not specified a callback url, the verifier will be displayed on screen and the user will have to copy it and paste it into your application.

3. Get Access Token

Send a POST request to the access Token URL: https://<domain>/oauth2/token/

POST body parameters:
Request Field Name Description
client_idClient ID issued in step 1.
client_secretClient Secret issued in step 1.
codeAuthorization code issued in step 2.
redirect_uriRedirect URI for the application.

The response will either be a 400 status with the following text:
{"error": "invalid_grant"}

or a 200 status with a response similar to
{ "access_token": ACCESS_TOKEN, "expires_in": EXPIRES_IN, "refresh_token": REFRESH_TOKEN, "scope": SCOPES, "token_type": Bearer }
You will need to save the ACCESS_TOKEN and REFRESH_TOKEN for future use. Yoy may also want too save the EXPIRES_IN value to know when a refresh is needed.

5. Make Calls to the API

You can verify your calls to the api by passing OAuth credientials as an HTTP header or as request parameters.

OAuth2 HTTP Header
Authorization: "Bearer ACCESS_TOKEN"