Skip to content

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.

Every club has its own sign-in server. Copy its address in Crewcade:

  1. Open Settings and choose Developers. Open the Connected apps tab.
  2. 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-configuration

The issuer is the same address without /.well-known/openid-configuration:

https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t

The reply of the discovery address gives you these endpoints:

EndpointWhere it lives
AuthorizeOn 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.

ScopeWhat the app can do
openidGet an ID token. The member sees no line for it.
profileSee the name and photo of the member.
emailSee the email address of the member.
registrationsSee the events of the member. Sign the member up for free events and cancel free signups.
peopleSee 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.

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.

ParameterNeededMeaning
response_typeYesAlways code.
client_idYesYour client ID.
redirect_uriYesOne of your return URLs. It must match exactly.
scopeYesThe scopes you want.
code_challengeYesThe PKCE challenge.
code_challenge_methodYesAlways S256. Crewcade does not accept plain.
stateNoA random value. Crewcade sends it back. Check it.
nonceNoA random value. It appears in the ID token.
promptNoconsent 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_STATE

The 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.

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.

Send a POST to the token endpoint. Use the form format application/x-www-form-urlencoded.

Terminal window
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_VERIFIER

A server app must also prove who it is. Send the secret in one of two ways:

  • Authorization: Basic with the client ID and secret (client_secret_basic).
  • The form fields client_id and client_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_token comes only when you asked for openid.
  • The access token is a random string. It is not a JWT. Do not read it.

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.

ClaimMeaning
issThe issuer.
subThe member ID.
audYour client ID.
exp, iatWhen the token ends and when it began.
nonceYour nonce, if you sent one.
auth_timeWhen the member signed in, if known.

Check the signature, iss, aud, exp and nonce.

Send the access token as a bearer token.

Terminal window
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.

When the access token ends, trade the refresh token for new tokens.

Terminal window
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_id

Every 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.

Terminal window
curl https://api.crewcade.com/api/oauth/w/k3m9x2pq4r7t/revoke \
-d token=ccr_your_refresh_token \
-d client_id=cca_your_client_id

The reply is always 200. Revoking a refresh token also ends the tokens that came with it.

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.
  • 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.

Token errors follow RFC 6749. The reply is JSON with error and error_description.

ErrorMeaning
invalid_requestA parameter is missing or wrong.
invalid_clientThe client ID or secret is wrong. A server app must always send its secret.
invalid_grantThe code or refresh token is wrong, used, ended or revoked. The verifier or redirect_uri does not match.
unsupported_grant_typeUse only authorization_code or refresh_token.
invalid_scopeThe scope is unknown. Or you asked for more than the member allowed.
temporarily_unavailableSign-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.

  • 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 the Retry-After header.