Contents

Authorization

The ShootProof API uses OAuth 2.0 to authorize users, providing access to our API. We use the authorization code grant type (commonly referred to as three-legged OAuth) with refresh tokens.

Tip

To help us streamline the signup process for users who don’t yet have a ShootProof studio account, see New Studio Signup.

Scope

To authorize access to the ShootProof API, you must include the following scope in your OAuth requests.

studio

Hint

The studio scope may be combined with other API scopes if you are using the same authorization for our legacy API. See the developer documentation of our legacy API for more information.

Authorization Code Request

Redirect your user to the following URL, using these query string parameters. We will present the user with a ShootProof login page. Once successfully logged in, the user will be prompted to grant (authorize) your app access to their ShootProof data, and then we will redirect the user to your redirect url with a code query string parameter. You may then exchange this temporary code for an access token.

Authorization Endpoint

https://auth.shootproof.com/oauth2/authorization/new

Query Parameters

response_type: You MUST provide a response_type with a value of code.
client_id: You MUST provide the ShootProof client ID created for your app.
redirect_uri: The URL to which we’ll redirect the user, after they have granted your app access to their ShootProof account. This MUST match one of the redirect URLs provided for your app.
scope: A space-separated list of scopes (permissions) for which your app is requesting access from the user. For access to the ShootProof API, you MUST include the studio scope.
state: You SHOULD include a state parameter in your request. This value is opaque to ShootProof; we simply include this value when redirecting the user back to your app. You can check its value to determine the validity of the request. In this way, it is useful to prevent cross-site request forgeries.
oauth_signup: You MAY include the oauth_signup parameter to streamline the ShootProof studio signup process for users new to ShootProof. See New Studio Signup for more information.

Example

https://auth.shootproof.com/oauth2/authorization/new
    ?response_type=code
    &client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    &redirect_uri=https://example.com/redirect
    &scope=studio
    &state=9deafe2dfff0b0fabcbac628090fadd662ef0302
    &oauth_signup=eyJzdHVkaW9OYW1lIjoiRG95bGUgU3R1ZGlvIiwiZmlyc3ROYW1lIjoiU2FtYW50aGEiLCJsYXN0TmFtZSI6IkRveWxlIiwicGhvbmUiOiIoNTU1KSA1OTgtMzQxMCIsImVtYWlsIjoic2FtQGV4YW1wbGUuY29tIn0=

Upon successful login or signup, ShootProof will redirect the user back to your app, using the given redirect_uri and state values:

https://example.com/redirect
    ?state=9deafe2dfff0b0fabcbac628090fadd662ef0302
    &code=68a8bdc685c6d48fbd84870ebe4371cd7ffc6f58

You may then exchange the given code for an access token.

Errors

The ShootProof authorization service follows the guidelines in RFC 6749 § 4.1.2.1 for communicating authorization code request errors.

Access Token Request

Once you have obtained an authorization code, you may exchange it for an access token. For this request, you MUST NOT redirect the user. This is a POST request that is performed in the background from your secure server. The response of this request will give you an access token that you may then use to make authenticated requests using the API. Along with the access token, we will provide expiration information and a refresh token that may be used to get a new access token prior to expiration.

Access tokens last 2 weeks, though it is a good idea to refresh before the access token expires.

Danger

The access token and refresh token are sensitive pieces of information and MUST be treated just like a user’s password and other personal information. You MUST encrypt these values at rest.

Access Token Endpoint

https://auth.shootproof.com/oauth2/authorization/token

POST Parameters

grant_type: You MUST provide a grant_type with a value of authorization_code.
client_id: You MUST provide the ShootProof client ID created for your app.
code: You MUST provide the authorization code received when the user redirected back to your redirect URL in the authorization code request step.
redirect_uri: The redirect_uri MUST match the value used in the authorization code request step. We will not use this to redirect user; it is used as a verification check.
scope: A space-separated list of scopes (permissions) for which your app is requesting access from the user. For access to the ShootProof API, you MUST include the studio scope.

Response Properties

A successful access token response contains a JSON object with the following properties:

access_token: The access token you may use to access the user’s ShootProof data (see authentication).
expires_in: The lifetime in seconds of the access token, relative to the time the response was generated. For example, if the value is 3600, the access token would expire in one hour from the time of the response.
refresh_token: A token that may be used to obtain a new access token before the current one expires (see Refresh Token Request).
scope: A space-separate list of scopes (permissions) for which this access token may be used.
token_type: The value of token_type will be bearer. At this time, ShootProof supports only bearer token authentication.

Example

POST /oauth2/authorization/token HTTP/1.1
Accept: */*
Content-Length: 183
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: auth.shootproof.com

grant_type=authorization_code&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&code=68a8bdc685c6d48fbd84870ebe4371cd7ffc6f58&redirect_uri=https%3A%2F%2Fexample.com%2Fredirect&scope=studio

HTTP/1.1 200 OK
Content-Length: 192
Content-Type: application/json
Date: Tue, 07 Nov 2017 23:33:24 GMT

{
  "access_token": "f75dfe33f56c3793795dca279471f08bd96f2a86",
  "expires_in": 1209600,
  "refresh_token": "306e09d9bca79158b45db25c91c4d561ddb1b4b7",
  "scope": "studio",
  "token_type": "bearer"
}

Errors

The ShootProof access token service follows the guidelines in RFC 6749 § 5.2 for communicating access token request errors.

Refresh Token Request

A refresh token is a long-lasting credential used to request additional access tokens. The refresh token request is very similar to the access token request.

Refresh Token Endpoint

https://auth.shootproof.com/oauth2/authorization/token

POST Parameters

grant_type: You MUST provide a grant_type with a value of refresh_token.
refresh_token: You MUST provide a valid refresh token received when an access token was obtained in the access token request step.
scope: A space-separated list of scopes (permissions) for which your app is requesting access from the user. The requested scope MUST NOT include any scope not originally granted by the resource owner.

Response Properties

Response properties for a refresh token are identical to those for an access token. See the access token response properties for more information.

Example

POST /oauth2/authorization/token HTTP/1.1
Accept: */*
Content-Length: 94
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: auth.shootproof.com

grant_type=refresh_token&refresh_token=306e09d9bca79158b45db25c91c4d561ddb1b4b7&scope=studio

HTTP/1.1 200 OK
Content-Length: 192
Content-Type: application/json
Date: Wed, 08 Nov 2017 02:48:48 GMT

{
  "access_token": "11ebcb3729dd6f71377bc760ed8ce591719e9234",
  "expires_in": 1209600,
  "refresh_token": "fe58a5e2480f968c1dbfae7c2719ce62d8da12d2",
  "scope": "studio",
  "token_type": "bearer"
}

Errors

The ShootProof refresh token service follows the guidelines in RFC 6749 § 5.2 for communicating refresh token request errors.