V1 is an integration as a third-party client. A future iteration is intended to support first-party integration once we have migrated most accounts over.

SMA refers to Spordle My Account

Requirements

• Replace Play account registration flow with SMA login

• Link existing Play accounts to SMA accounts

• Continue to allow login with Play accounts but prompt to link SMA account if not linked

• Session durations and global logout not implemented

Implementation

Login and Registration Flow

1. User clicks on Login with SMA

   1. Registration button has been removed

2. User completes the SMA flow and is successfully redirected back to Play with an access token

   1. SMA flow is out of scope for this document

3. Play app send the token to a new Play API for authentication

4. API will use the token to retrieve account details (account id, email address) and linked participant details (id, name, etc) from SMA

5. Play to sync account (based on externalId and email, similar to participants)

   1. If neither exist, create a new account with the email and externalId

   2. If the email exists but externalId does not, update the account with the externalId.

   3. If the externalId exists with a mismatched email, update email

6. Play to sync identities and participants

   1. Import participants based on the linked participant details

      1. This process already exists as part of the sync

      2. How do we match tenants?

   2. Create any missing account identities

      1. Primary to be determined from SMA?

   3. API will create any additional contacts for notifications

7. API returns a Play access token to the app with the same response/behaviour as the password flow

8. If the participant doesn’t have any permissions, the existing unauthorized message will be shown

Linking Flow

1. User logs in with their Play credentials

2. /accounts/current request will flag if the account is linked or not based on if externalId is set on the account

   1. If this flag is not set, skip this flow

3. Profile page will show a link my SMA alert prompt

4. Alert makes a request to the Play API which will make a request to the SMA API to search for accounts by email address (maybe participant ID?)

   1. If there’s a matching account, message will offer to link the account

   2. If there isn’t a matching account, message will suggest creating an account in SMA

   3. Alert is hidden until the request is completed, no loading state

5. Alert action will link to SMA to prompt link process

   1. Out of scope for this document, but redirect back to Play would follow registration flow

Model Changes

• Add externalId on Account to indicate the link to the SMA account

API Changes

• Login API with SMA token

• Add linked account flag to /accounts/current

Additional information

My Account

https://api.account.spordle.dev/doc/

Terminology