SavvyCal API
Endpoints
Resources
Webhooks
SavvyCal API
Home

Authentication

There are two methods for authenticating: personal access tokens for testing and controlling your own account via the API, and OAuth for building integrations where you are operating on behalf of another user.

Personal Access Tokens

Personal access tokens are managed via the SavvyCal interface. To create one, navigate to your Developer Settings:

The personal access tokens interface

Click “Create a token” and give your token a name (it’s best to indicate how you plan to use the token). Then, use the Authorization header and the Bearer realm to authenticate your requests with your token:

# Example cURL request
curl -H 'Authorization: Bearer pt_secret_XXXXXXXXXXX' https://api.savvycal.com/v1/me

OAuth

We follow the OAuth 2 specification for obtaining credentials. Access tokens are short-lived (2 hours) and can be refreshed using the long-lived refresh token issued during the authorization flow.

Register your application

First, create an OAuth application in your SavvyCal Settings. You’ll need to provide the following information:

  • Name: the name of your application
  • Redirect URI: the callback URL to redirect to with a code after the authorization flow (e.g. https://myapp.com/auth/savvycal/callback)

Once you create your app, you’ll receive a client ID and client secret to use in the OAuth flow.

Requesting access to an account

It’s generally a good idea to use an OAuth library to handle this process. There are open source libraries available in most common languages. If you’re implementing this flow manually (or just want to understand what going on behind the scenes in one of these libraries), continue on!

To initiate the OAuth flow, send the user to the authorize endpoint and replace <your-client-id> and <your-redirect-uri> respectively:

https://savvycal.com/oauth/authorize?response_type=code&client_id=<your-client-id>&redirect_uri=<your-redirect-uri>

The user will be presented with OAuth screen like this:

An example of the OAuth screen

When the user accepts, they’ll be redirected to your redirect URI with a code parameter:

https://myapp.com/callback?code=<auth-code>

The auth code in the query string can then be exchanged for an access token. Make a POST request to https://savvycal.com/oauth/token with the following body parameters (form-encoded):

Parameter Value
code The auth code from the query string.
client_id The client ID from your registered app.
client_secret The client secret from your registered app.
grant_type authorization_code
redirect_uri The redirect URI from your registered app.
POST /oauth/token HTTP/1.1
Host: https://savvycal.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

code=xxxxxxxxx
&client_id=xxxxxxxxx
&client_secret=xxxxxxxxx
&grant_type=authorization_code
&redirect_uri=https://myapp.com/callback

The successful response will have a JSON body with the following properties:

Property Description
access_token A Bearer token to use in the Authorization header of API requests.
refresh_token A refresh token to use to obtain a new access token. You should store this in your database in you need long-term access to the API.
expires_in The number of seconds the access_token will remain valid (currently 7200).
token_type bearer

To refresh your access token, send a POST request to https://savvycal.com/oauth/token with the following body parameters (form-encoded):

Parameter Value
refresh_token The refresh token originally issued in the authorization flow.
grant_type refresh_token
client_id The client ID from your registered app .
client_secret The client secret from your registered app.
POST /oauth/token HTTP/1.1
Host: https://savvycal.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

refresh_token=xxxxxxxxx
&client_id=xxxxxxxxx
&client_secret=xxxxxxxxx
&grant_type=refresh_token

The response will be the same shape as the original token response.

Authenticating requests

To authenticate your API requests, include the your access token in your Authorization header, prefexed with Bearer :

GET /me HTTP/1.1
Host: https://api.savvycal.com
Accept: application/json
Authorization: Bearer xxxxxxxxxxxxxxxxxx