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.

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:

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.

with the following parameters:

and the following headers:

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:

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.