OAuth 2.0

With OAuth 2.0, Hipsy users can connect your app to their account without sharing a password or API key. The user logs in on Hipsy, chooses what your app may access, and your app gets an access token for the Hipsy API.

Register your app

You can't register an app yourself. Send an email to info@hipsy.nl and we create the app for you. Include:

• Name of the app, as users will see it on the login and consent screen.
• Short description of what the app does. It is shown on the consent screen.
• Logo: a square image (PNG or SVG), at most 1 MB.
• Company or developer, with a website and a contact email address.
• Redirect URIs: the exact URLs Hipsy may send users back to after they approve, for example https://app.example.com/hipsy/callback. You can give more than one, for example for a test environment.
• Scopes the app needs, and what you use them for. See scopes.

We send you:

• the client_id of your app;
• the client_secret. It is shown to us only once when it is created, so store it safely. If it is lost or leaked, ask us for a new one: the old secret stops working right away.

Your app needs a server (backend) that exchanges codes and refreshes tokens with the client secret.

Endpoints

Hipsy supports the authorization code flow and refresh tokens. Other grants, like the implicit, password and client credentials grants, are not available.

Scopes

Scopes define what your app may access. There are two kinds:

• Account scopes apply to the user.
• Organisation scopes apply to an organisation. On the consent screen the user chooses for which of their organisations your app gets each organisation scope.

All scopes are read only. Your app can only request the scopes we enabled for it. Request only what you need: users trust an app more when it asks for less.

The authorization flow

1. Create a state

For every authorization, create a random state and store it in the session of the user. You use it in step 3 to check that the response belongs to a request your app started.

2. Send the user to Hipsy

Redirect the user to the authorization endpoint:

https://hipsy.nl/oauth/authorize
    ?client_id={client_id}
    &redirect_uri=https://app.example.com/hipsy/callback
    &response_type=code
    &scope=organisations:read organisation.events:read
    &state={state}

The user logs in, if they aren't logged in yet, and sees the consent screen with your name and logo. There they:

• can uncheck account scopes, like organisations:read;
• choose per organisation which organisation scopes your app gets;
• approve or deny.

The consent screen is shown every time, also when the user approved your app before. The earlier choice is pre-checked.

3. Handle the redirect

After the user approves, Hipsy redirects to your redirect URI with a code and the state:

https://app.example.com/hipsy/callback?code={code}&state={state}

Check that state is the value you created in step 1. The code is valid for 10 minutes and can be used once.

If the user denies, or something is wrong with the request, Hipsy redirects with an error instead:

An unknown client_id or a redirect_uri that doesn't match shows an error on Hipsy, without redirecting.

4. Exchange the code for tokens

Make a POST request to the token endpoint:

curl -X POST https://hipsy.nl/oauth/token \
   -H "Accept: application/json" \
   -d grant_type=authorization_code \
   -d client_id={client_id} \
   -d client_secret={client_secret} \
   -d redirect_uri=https://app.example.com/hipsy/callback \
   -d code={code}

The redirect_uri must be the same as in step 2. The response contains the tokens:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "refresh_token": "def50200a8d5..."
}

5. Call the API

Send the access token as a Bearer token, like an API key:

curl https://api.hipsy.nl/v1/me \
   -H "Accept: application/json" \
   -H "Authorization: Bearer {access_token}"

Refresh the access token

An access token is valid for 1 hour. Request a new one with the refresh token:

curl -X POST https://hipsy.nl/oauth/token \
   -H "Accept: application/json" \
   -d grant_type=refresh_token \
   -d client_id={client_id} \
   -d client_secret={client_secret} \
   -d refresh_token={refresh_token}

The response has the same format as in step 4, with a new access token and a new refresh token. Store the new refresh token: the old one stops working. A refresh token that isn't used expires after 30 days. Then the user has to authorize your app again.

What the user granted

The user decides what your app gets, so it can be less than you requested:

• Without an account scope, the endpoint returns status code 403.
• List organisations returns all organisations of the user, also those they didn't grant your app.
• For an organisation the user didn't grant a scope for, the organisation endpoint returns status code 403. Handle this as "no access to this organisation", not as an error of your app.

When the user changes their choice later, by authorizing your app again, it applies right away, also to access tokens you already have.

Disconnecting

Users see the apps they connected on hipsy.nl under Account → Gekoppelde apps, with what each app may access per organisation. When they disconnect your app, its access and refresh tokens stop working at once and the API returns status code 401. To connect again, the user has to go through the authorization flow again.