OAuth Provider Setup

SemaLink supports sign-in via Google, Microsoft, GitHub, and Apple. Each provider requires credentials created in that provider's developer console and set as environment variables on the API server.

The callback URLs the API registers follow this pattern:

{API_URL}/api/v1/auth/{provider}/callback

Set API_URL in the API's .env to your server's base URL — this controls what redirect URI gets sent to each provider during the OAuth flow.

# dev
API_URL=http://localhost:3000

# production
API_URL=https://api.semalink.africa

---

Google

Console: console.cloud.google.com → APIs & Services → Credentials → Create OAuth 2.0 Client ID (Application type: Web application)

GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret

Authorised redirect URIs to register:

http://localhost:3000/api/v1/auth/google/callback
https://api.semalink.africa/api/v1/auth/google/callback

---

Microsoft

Console: portal.azure.com → App registrations → New registration → Authentication → Add a platform → Web

MICROSOFT_CLIENT_ID=your_application_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret_value   # from Certificates & secrets tab
MICROSOFT_TENANT=common                             # use your tenant ID to restrict to one org

Redirect URIs to register:

http://localhost:3000/api/v1/auth/microsoft/callback
https://api.semalink.africa/api/v1/auth/microsoft/callback

Tenant

Keep MICROSOFT_TENANT=common to allow any Microsoft/Outlook account. Set it to your Azure AD tenant ID (e.g. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) to restrict login to your organisation only.

---

GitHub

Console: GitHub → Settings → Developer settings → OAuth Apps → New OAuth App

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

Authorization callback URL:

http://localhost:3000/api/v1/auth/github/callback

One callback URL per app

GitHub OAuth Apps only allow a single callback URL. Create a separate OAuth App for production with the https://api.semalink.africa/... callback, and a separate one for local development.

---

Apple

Apple Sign In is the most involved setup. You need an Apple Developer account ($99/year).

Console: developer.apple.com → Certificates, IDs & Profiles

Steps:

1. Create an App ID — enable "Sign In with Apple" capability
2. Create a Services ID — this becomes your APPLE_CLIENT_ID. Add your domain and register the return URL
3. Create a Key — enable "Sign In with Apple", download the .p8 private key file

APPLE_CLIENT_ID=com.semalink.app         # your Services ID identifier
APPLE_TEAM_ID=XXXXXXXXXX                  # 10-char Team ID (top-right of developer.apple.com)
APPLE_KEY_ID=XXXXXXXXXX                   # Key ID shown when you create the key
APPLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\nMIGH...\n-----END PRIVATE KEY-----

To set APPLE_PRIVATE_KEY: open the downloaded .p8 file, copy the contents, and replace newlines with \n (or use actual newlines if your secret manager supports multi-line values).

Return URL to register on the Services ID:

https://api.semalink.africa/api/v1/auth/apple/callback

HTTPS required

Apple does not allow localhost as a redirect URI. For local development use a tunnel such as ngrok and register the tunnel URL in the Services ID.

Name only sent once

Apple only sends the user's name on the very first authorisation. Subsequent logins return the sub and email only. SemaLink handles this — the name is captured and stored on first sign-in.

---

Environment variable summary

All variables are optional. If a provider's variables are absent the corresponding button returns 501 Not configured.

Variable	Provider	Required
GOOGLE_CLIENT_ID	Google	Yes (for Google login)
GOOGLE_CLIENT_SECRET	Google	Yes (for Google login)
MICROSOFT_CLIENT_ID	Microsoft	Yes (for Microsoft login)
MICROSOFT_CLIENT_SECRET	Microsoft	Yes (for Microsoft login)
MICROSOFT_TENANT	Microsoft	No (default: common)
GITHUB_CLIENT_ID	GitHub	Yes (for GitHub login)
GITHUB_CLIENT_SECRET	GitHub	Yes (for GitHub login)
APPLE_CLIENT_ID	Apple	Yes (for Apple login)
APPLE_TEAM_ID	Apple	Yes (for Apple login)
APPLE_KEY_ID	Apple	Yes (for Apple login)
APPLE_PRIVATE_KEY	Apple	Yes (for Apple login)