OAuth Workflow

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

OAuth 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.

GitShare supports OAuth 1. We are working on adding OAuth 2, which is currently in draft form.

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 OAuth, 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, this 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 yeild your Client Token and Client Secret. These will be used throughout the OAuth process and you should save these in your application.

2. Request Token

Token Request URL: https://app.gitshare.io/oauth/request_token/

This endpoint supports both POST and GET as long as properly encoded.

Request Field Name Description
oauth_version"1.0" We currently only support version 1.0
oauth_nonceGenerate a nonce. We support alpha-numeric charaters up 64 chars.
oauth_timestamptimestamp
oauth_consumer_keyThis is the Client Token issued in step 1.
oauth_signature_method"PLAINTEXT"
oauth_signatureClient Secret issued in step1. Append & at the end of this field.

The response will either be a 403 status with the following text:
Could not verify OAuth request.

or a 200 status with
oauth_token_secret=REQUEST_SECRET&oauth_token=REQUEST_TOKEN
You will need to save the REQUEST_TOKEN and REQUEST_SECRET for future use.

3. Generate Authorization Url

To generate the authorization url, you will concatenate the base url and your request token returned from the call in step 2.

Example Authorization Url: https://app.gitshare.io/oauth/authorize/?oauth_token=REQUEST_TOKEN

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.

4. Get Access Token

Access Token URL: https://app.gitshare.io/oauth/access_token/

Request Field Name Description
oauth_version"1.0" We currently only support version 1.0
oauth_nonceGenerate a nonce. We support alpha-numeric charaters up 64 chars.
oauth_timestamptimestamp
oauth_verifierVerifier returned from step 3 above.
oauth_signature_method"PLAINTEXT"
oauth_consumer_keyClient Token issued in step 1.
oauth_tokenRequest Token issued in response to step 2.
oauth_signatureCLIENT_SECRET&REQUEST_SECRET
Client Secret issued in step 1 and Request Secret issued in response to step 2.
The easiest thing to miss here is the concatentation together with the &.

The response will either be a 403 status with the following text:
Could not verify OAuth request.

or a 200 status with
oauth_token_secret=ACCESS_SECRET&oauth_token=ACCESS_TOKEN
You will need to save the ACCESS_TOKEN and ACCESS_SECRET for future use.

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.

OAuth HTTP Header
Authorization: OAuth oauth_consumer_key="CLIENT_TOKEN",
oauth_token="ACCESS_TOKEN",
oauth_nonce="random_nonce",
oauth_timestamp="current_timestamp",
oauth_signature_method="PLAINTEXT",
oauth_version="1.0",
oauth_signature="CLIENT_SECRET&ACCESS_SECRET"