Sign in with Crewcade
Members of your club can sign in to your own website or app. They use their Crewcade account. Crewcade uses OAuth 2.1 with the authorization code flow and PKCE. It also supports OpenID Connect.
Before you start, add your app in Crewcade. See Connected apps. You get a client ID. A server app also gets a client secret.
Find your club
Section titled “Find your club”Every club has its own sign-in server. Copy its address in Crewcade:
- Open Settings and choose Developers. Open the Connected apps tab.
- Find your app. Click Copy next to Sign-in settings URL.
This is the discovery address. It lists every endpoint. It looks like this:
https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/.well-known/openid-configurationThe issuer is the same address without /.well-known/openid-configuration:
https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7tThe reply of the discovery address gives you these endpoints:
| Endpoint | Where it lives |
|---|---|
| Authorize | On the own address of the club, /api/oauth/authorize |
| Token | {issuer}/token |
| Revoke | {issuer}/revoke |
| User info | {issuer}/userinfo |
| Signing keys | {issuer}/jwks |
Read these addresses from the discovery reply. Do not build them by hand.
Scopes
Section titled “Scopes”| Scope | What the app can do |
|---|---|
openid | Get an ID token. The member sees no line for it. |
profile | See the name and photo of the member. |
email | See the email address of the member. |
registrations | See the events of the member. Sign the member up for free events and cancel free signups. |
people | See the people going to an event that the member goes to. |
Send the scopes in the scope parameter, separated by spaces. An unknown scope gives an invalid_scope error.
Step 1: Send the member to Crewcade
Section titled “Step 1: Send the member to Crewcade”Make a random code_verifier with 43 to 128 characters. Use letters, digits and these marks: -._~. Then make the code_challenge. It is the SHA-256 hash of the verifier, written in base64url.
Open this address in the browser of the member. Use the authorize endpoint from discovery.
| Parameter | Needed | Meaning |
|---|---|---|
response_type | Yes | Always code. |
client_id | Yes | Your client ID. |
redirect_uri | Yes | One of your return URLs. It must match exactly. |
scope | Yes | The scopes you want. |
code_challenge | Yes | The PKCE challenge. |
code_challenge_method | Yes | Always S256. Crewcade does not accept plain. |
state | No | A random value. Crewcade sends it back. Check it. |
nonce | No | A random value. It appears in the ID token. |
prompt | No | consent always shows the screen. none never shows it. |
Send each parameter once. Crewcade ignores unknown parameters. A repeated parameter is an error.
https://yourclub.crewcade.com/api/oauth/authorize?response_type=code&client_id=cca_your_client_id&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid%20profile%20email&code_challenge=YOUR_CHALLENGE&code_challenge_method=S256&state=YOUR_STATEThe member signs in on the page of the club. The member can use a password, Google, LINE or a 6-digit email code. Then the member sees what your app can do. The member taps Allow or Cancel. The app never sees the password. Crewcade remembers the choice of the member.
Your app can ask for registrations and people later. A member who already allowed your app sees only the new permissions. The member does not allow the old ones again.
With prompt=none, the member does not see a screen. If the member has not allowed the app yet, you get consent_required.
Step 2: Read the answer
Section titled “Step 2: Read the answer”Crewcade sends the member to your return URL.
On success the address has code, state and iss. Check that state is the value you sent. Check that iss is the issuer.
On a problem the address has error, state and iss. If the member taps Cancel, the error is access_denied.
Sometimes the client_id is unknown or the redirect_uri does not match. Then Crewcade shows its own error page. Crewcade does not send the member to your app.
The code lasts 60 seconds. You can use it once.
Step 3: Trade the code for tokens
Section titled “Step 3: Trade the code for tokens”Send a POST to the token endpoint. Use the form format application/x-www-form-urlencoded.
curl https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/token \ -d grant_type=authorization_code \ -d code=THE_CODE \ -d redirect_uri=https://app.example.com/callback \ -d client_id=cca_your_client_id \ -d code_verifier=YOUR_VERIFIERA server app must also prove who it is. Send the secret in one of two ways:
Authorization: Basicwith the client ID and secret (client_secret_basic).- The form fields
client_idandclient_secret(client_secret_post).
A website or mobile app sends no secret. The code_verifier is its proof.
The reply:
{ "access_token": "ccm_...", "token_type": "Bearer", "expires_in": 900, "refresh_token": "ccr_...", "scope": "openid profile email", "id_token": "eyJ..."}- The access token lasts 15 minutes (900 seconds).
- The refresh token lasts 30 days.
- The
id_tokencomes only when you asked foropenid. - The access token is a random string. It is not a JWT. Do not read it.
The ID token
Section titled “The ID token”The ID token is a JWT signed with RS256. Get the public keys from the jwks endpoint. The kid in the token header says which key to use.
| Claim | Meaning |
|---|---|
iss | The issuer. |
sub | The member ID. |
aud | Your client ID. |
exp, iat | When the token ends and when it began. |
nonce | Your nonce, if you sent one. |
auth_time | When the member signed in, if known. |
Check the signature, iss, aud, exp and nonce.
Call the API as the member
Section titled “Call the API as the member”Send the access token as a bearer token.
curl https://api.crewcade.com/api/v1/me \ -H "Authorization: Bearer ccm_your_access_token"You can call GET /v1/me, GET /v1/workspace and the events endpoints. See Me and workspace and Events. With the registrations scope you can also call the registrations endpoints. With the people scope you can call People to meet. The userinfo endpoint gives the same data as GET /v1/me. A member token cannot call the members endpoints or GET /v1/events/{id}/registrations.
Each member and app pair can send 60 requests per minute.
Step 4: Refresh
Section titled “Step 4: Refresh”When the access token ends, trade the refresh token for new tokens.
curl https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/token \ -d grant_type=refresh_token \ -d refresh_token=ccr_your_refresh_token \ -d client_id=cca_your_client_idEvery refresh gives you a new refresh token. The old one stops working. Always save the new one.
Someone might use an old refresh token again. Then Crewcade signs the member out of your app everywhere. The member must sign in again. This protects the member if a token leaks.
You can ask for fewer scopes when you refresh. You cannot ask for more.
Sign out: revoke a token
Section titled “Sign out: revoke a token”curl https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/revoke \ -d token=ccr_your_refresh_token \ -d client_id=cca_your_client_idThe reply is always 200. Revoking a refresh token also ends the tokens that came with it.
When a member loses access
Section titled “When a member loses access”Access stops at once when:
- the member disconnects your app.
- the member is suspended or leaves the club.
- the member account is deleted or blocked.
- you turn off or delete the app.
- you replace the client secret.
Browser apps and server apps
Section titled “Browser apps and server apps”- A website or mobile app is a public client. It has no secret. PKCE protects it.
- A server app is a confidential client. It keeps a secret on the server.
A browser app can call the token endpoint and /v1. It must call from the origins of its return URLs. These calls send no cookies.
Errors
Section titled “Errors”Token errors follow RFC 6749. The reply is JSON with error and error_description.
| Error | Meaning |
|---|---|
invalid_request | A parameter is missing or wrong. |
invalid_client | The client ID or secret is wrong. A server app must always send its secret. |
invalid_grant | The code or refresh token is wrong, used, ended or revoked. The verifier or redirect_uri does not match. |
unsupported_grant_type | Use only authorization_code or refresh_token. |
invalid_scope | The scope is unknown. Or you asked for more than the member allowed. |
temporarily_unavailable | Sign-in is not available right now. Try again later. |
If a code is used twice, Crewcade rejects it. It also revokes the tokens from the first use.
A call to /v1 with a bad token gives 401 and invalid_token. A missing scope gives 403 and insufficient_scope.
Rate limits
Section titled “Rate limits”- The token endpoint allows 120 requests per minute for each client.
- The token endpoint allows 30 requests per minute for each IP address.
- A too-fast call gives
429. Wait the number of seconds in theRetry-Afterheader.