Connect a business

Before you start

• Your client id and client secret.
• A return address registered with your app. Shiftly only sends people back to an address on that list, matched exactly.
• A PKCE implementation: a verifier of 43 to 128 characters from the unreserved set, and its S256 challenge.

1. Build the authorize request

Send the person's browser to that address. Shiftly checks the app and the return address first. If either is wrong, it does not send the person to your address at all; it shows them that the connection request has expired. For any other problem, such as a permission your app is not allowed to ask for, it sends them back to you with error and error_description.

2. What the owner sees

The person signs in to Shiftly if they are not already. Shiftly then shows a consent screen with your app's name, the business it will have access to (or, with business_selection=multiple, the businesses to tick), and two columns: what it will be able to view, and what it will be able to add or change. The screen also says what your app cannot do, and that staff dates of birth and addresses are shared when you ask for staff details or leave.

• Someone who manages several businesses chooses one, or ticks several when you sent business_selection=multiple. Each business is its own connection, with its own credentials.
• When ticking several, nothing starts ticked, and a business the person can't connect is named with the reason. If one ticked business can't be connected, or your app has no room for all of them, nothing is connected.
• Only a business owner, or a manager who can manage team access, can connect an app. Anyone else is told to ask an owner.
• A permission the person does not hold themselves is shown as one they can't share. The connection is created without it, and an owner can grant it later by connecting again.
• If the business is already connected to your app, the button reads Update access and the new permissions replace the old.
• While your app is in limited release and at its connection limit, a new business is told the app can't take new connections yet.

The consent screen itself is valid for 15 minutes from the authorize request. After that the person is told to start again from your product.

3. Handle the return

Allowed: the browser lands on your return address with code and state. Check that state matches what you sent, then exchange the code within five minutes.

https://yourapp.example/shiftly/callback?code=xxxxxxxx&state=...

Cancelled: the person pressed Cancel, or Back to your app from a screen that could not proceed. You receive error=access_denied and your state. Nothing was shared.

https://yourapp.example/shiftly/callback?error=access_denied&state=...

4. Exchange the code

Authenticate your app with HTTP Basic (client id as the username, secret as the password), or with client_id and client_secret in the JSON body. Send grant_type, code, the same redirect_uri and your code_verifier.

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "shf_rt_...",
  "scope": "roster:read roster:write offline_access",
  "connection_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "business_id": "66f1c2a4b3d9e8f7a6b5c4d2"
}

The scope in the response is what was actually granted, which can be less than you asked for. Store each refresh token against its connection_id. A code can be exchanged once; a second exchange is refused and every refresh token it led to is revoked, including ones already renewed, so never retry an exchange that returned a token.

Every code exchange also carries connections: one entry for every business that was connected, in name order, each with its own credentials and scope. It has one entry unless you sent business_selection=multiple and the person ticked several. The top-level fields repeat the first entry, so a client that reads only those still works for one business. A manager can share different things at different businesses, so read each entry's scope. A business that was disconnected between consent and exchange is left out.

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "shf_rt_...",
  "scope": "roster:read pay:read offline_access",
  "connection_id": "66f1c2a4b3d9e8f7a6b5c4d3",
  "business_id": "66f1c2a4b3d9e8f7a6b5c4d2",
  "connections": [
    {
      "access_token": "eyJhbGciOiJFUzI1NiIs...",
      "token_type": "Bearer",
      "expires_in": 1800,
      "refresh_token": "shf_rt_...",
      "scope": "roster:read pay:read offline_access",
      "connection_id": "66f1c2a4b3d9e8f7a6b5c4d3",
      "business_id": "66f1c2a4b3d9e8f7a6b5c4d2",
      "business_name": "Harbour Street Espresso"
    },
    {
      "access_token": "eyJhbGciOiJFUzI1NiIs...",
      "token_type": "Bearer",
      "expires_in": 1800,
      "refresh_token": "shf_rt_...",
      "scope": "roster:read offline_access",
      "connection_id": "66f1c2a4b3d9e8f7a6b5c4e7",
      "business_id": "66f1c2a4b3d9e8f7a6b5c4e6",
      "business_name": "The Wharf Hotel"
    }
  ]
}

What can go wrong