Find My Team

Authorization

The TeamSnap API requires that all requests to the API are authorized. To authorize a request, it must have a valid OAuth 2 access token passed in the request header.

New to OAuth 2?

This documentation does not cover the details of how OAuth 2 works or how to implement OAuth 2 client functionality. If you are unfamiliar with OAuth 2, details on how OAuth 2 works can be found at the official OAuth 2 spec, and at the great OAuth 2 Simplified Guide by Aaron Parecki.

OAuth 2 Client Libraries

TeamSnap recommends that you use an OAuth 2 client library to interact with TeamSnap's authorization service. A list of popular libraries is available at http://oauth.net/2/.

Creating OAuth 2 Credentials

To authorize your request, an application credential set must exist on our system. You can create an application with the following steps:

  1. Visit https://auth.teamsnap.com
  2. Login with your existing TeamSnap account (create a free account if you don't have one)
  3. Click on your name, and click on Your Applications

When you create your application, you will be asked to specify redirect URIs that your service will utilize to obtain credentials. If you pass in a redirect URI to the authorization service later, without this redirect URI being specified in your application credential set, it will be rejected to protect the security of yours and TeamSnap's users.

OAuth 2 Endpoints

The specific endpoints available for TeamSnap's OAuth 2 service are:

  • Authorization: GET https://auth.teamsnap.com/oauth/authorize
  • Token Exchange: POST https://auth.teamsnap.com/oauth/token
  • Token Revocation: POST https://auth.teamsnap.com/oauth/revoke

The OAuth 2 service does not provide an application credential / API endpoint.

Web Application Flow

Also commonly known as 3-Leg OAuth, the web application flow is the recommended flow for any system that has a server seperate from the client. The steps are as follows:

1. Redirect User to TeamSnap

In your application, you should redirect the user to the appropriate authentication URL:

GET https://auth.teamsnap.com/oauth/authorize

with the appropriate parameters:

Name Type Description
client_id string Required. The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.
redirect_uri string The URL where you want users to be sent after authorization. This URI MUST be a subpath of a URI specified when you registered your application.
scope string A space-seperated list of scopes (permissions) your application requires.
response_type string code or token. For the web application flow, this should always be code.

2. Authentication Callback

Once the user accepts your authorization request via TeamSnap, the authorization service will redirect the user back to the URI you specified in the redirect_uri parameter.

This request will have an appended code parameter that contains an authorization code eligible for exchange for a token. This code is only usable for 10 minutes and will expire after that.

https://example.com/callback?code=00108f1794bac...

3. Exchange Code for Token

The final step in this process is the token exchange.

Token Exchange Security

You should not, at any time, redirect the user to this URL. Token exchange should be performed on a trusted server ONLY to avoid exposing your client secret.
\`POST https://auth.teamsnap.com/oauth/token\`

with the following parameters:

Name Type Description
client_id string Required. The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.
client_secret string Required. The client_secret is the application secret you recieved from the TeamSnap Authorization Service when you registered your application.
redirect_uri string Required if you specified a redirect_uri in the authorization request. This redirect_uri MUST be the exact same as specified in the previous request.
code string Required. The authorization code recieved in the previous step for token exchange.
grant_type string Required. Should always be authorization_code.

and the following headers:

Name Type Description
content-length integer Required. If the post doesn't have a body, make sure the content-length is 0.

Token Authentication Flow

Also commonly known as 2-Leg OAuth, the token authentication flow is for use when you do not have available a non-client server to perform token exchange. The steps are as follows:

1. Redirect User to TeamSnap

In your application, you should redirect the user to the appropriate authentication URL:

GET https://auth.teamsnap.com/oauth/authorize

with the appropriate parameters:

Name Type Description
client_id string Required. The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.
redirect_uri string The URL where you want users to be sent after authorization. This URI MUST be a subpath of a URI specified when you registered your application.
scope string A space-seperated list of scopes (permissions) your application requires.
response_type string code or token. For the token authentication flow, this should always be token.

2. Authentication Callback

Once the user accepts your authorization request via TeamSnap, the authorization service will redirect the user back to the URI you specified in the redirect_uri parameter.

This request will have an appended access_token parameter passed as an HTML fragment that contains an authorization token eligible for immediate use.

https://example.com/callback#access_token=00108f1794bac...

Using OAuth 2 Credentials

You will need to pass the authorization token you obtained to TeamSnap's API via the Authorization HTTP header: Authorization: Bearer [TOKEN]

Scopes

These are the scopes available via the OAuth 2 service:

  • read - Default
  • write - Full write access.
  • write_members - Write access for members, contacts, and related sub-objects.
  • write_teams - Write access for team information.
  • write_events - Write access for team schedule (games and events).
  • write_users - Write access for user information.

To use multiple scopes, pass a space-seperated list to the scope parameter during authorization.

Revoking an Access Token

To revoke a user's Access Token, you may do that by submitting a POST to:

https://auth.teamsnap.com/oauth/revoke

and passing the following in as POST form data:

IMPORTANT Due to caching strategies employed on the TeamSnap platform, it may take up to 5 minutes for a revocation to bbe fully reflected on the platform.

Name Type Description
token string Required. The token that you are revoking.
client_id string Required. The client_id is the application identifier you recieved from the TeamSnap Authorization Service when you registered your application.
client_secret string Required. The client_secret is the application secret you recieved from the TeamSnap Authoirization Service when you registered the application.