Authentication with OAuth

To call the APIs you need an access token, which the application obtains with the OAuth authorization code flow with PKCE. There are three actors: your application (client), Riseact Account (authorization server) and Riseact Core (the APIs). The token gives access to the resources of the organization that installs the application.

1. Register the application

Register the application to get client_id and client_secret.

2. Redirect to the authorization server

The backend exposes an endpoint that redirects the user to Riseact Account with the client_id, the PKCE keys (code_verifier and code_challenge) and a random state against CSRF. Save code_verifier and state: you need them in the callback.

When an organization opens your application, Riseact loads the registered URL in the iframe adding the __organization parameter, with the organization slug. Pass it to the authorization server in the __organization parameter to skip the organization selection.

In node.js:

app.get('/oauth/authorize', (req, res) => {
  const { codeChallenge, codeVerifier } = generatePkceKeys();
  const state = crypto.randomBytes(16).toString('hex');

  // Salva codeVerifier e state come preferisci. In questo caso utilizziamo un database
  db.savePkceSession(state, { codeVerifier });

  const params = {
    client_id: CLIENT_ID,
    redirect_uri: 'https://your-app.com/oauth/callback',
    response_type: 'code',
    code_challenge_method: 'S256',
    code_challenge: codeChallenge,
    state,
    __organization: req.query.__organization,
  };

  res.redirect(`https://accounts.riseact.org/oauth/authorize/?${qs.stringify(params)}`);
});

With curl:

curl -X GET \
  "https://accounts.riseact.org/oauth/authorize/\
?client_id=CLIENT_ID\
&redirect_uri=https://your-app.com/oauth/callback\
&response_type=code\
&code_challenge_method=S256\
&code_challenge=YOUR_CODE_CHALLENGE\
&state=YOUR_RANDOM_STATE\
&__organization=YOUR_ORGANIZATION"

3. Handle the callback

After authentication the user comes back to the given redirect_uri, which must be among the registered ones. The backend checks that state matches the saved one, retrieves the code_verifier and exchanges the authorization code for an access token.

In node.js:

app.get('/oauth/callback', async (req, res) => {
  const { code, state } = req.query;

  // Recupera la sessione PKCE dal database usando lo state come chiave
  const session = await db.getPkceSession(state);

  if (!session) {
    return res.status(400).send('Invalid state');
  }

  const formData = {
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'authorization_code',
    code,
    redirect_uri: 'https://your-app.com/oauth/callback',
    code_verifier: session.codeVerifier,
  };

  const { data } = await axios.post('https://accounts.riseact.org/oauth/token/', qs.stringify(formData), {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
  });

  // Salva le credenziali ottenute come preferisci. In questo caso utilizziamo un database
  db.saveCredentials(data.access_token, data.refresh_token, data.expires_in);
});

With curl:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=YOUR_CODE" \
  -d "redirect_uri=https://your-app.com/oauth/callback" \
  -d "code_verifier=YOUR_CODE_VERIFIER" \
  https://accounts.riseact.org/oauth/token/

4. Call the APIs

Pass the access token in the Authorization header.

In node.js:

const { data } = await axios.get('https://core.riseact.org/admin/graphql/', {
  headers: {
    Authorization: `Bearer ${access_token}`,
  },
});

With curl:

curl -X GET \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://core.riseact.org/admin/graphql/

5. Renew the token

The access token expires (expires_in): renew it before it expires with the refresh token.

In node.js:

app.get('/oauth/refresh', async (req, res) => {
  const { refresh_token } = req.query;

  const formData = {
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'refresh_token',
    refresh_token,
  };

  const { data } = await axios.post('https://accounts.riseact.org/oauth/token/', qs.stringify(formData), {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
  });

  // Salva le credenziali ottenute come preferisci. In questo caso utilizziamo un database
  db.saveCredentials(data.access_token, data.refresh_token, data.expires_in);
});

With curl:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  https://accounts.riseact.org/oauth/token/