Developer Documentation

Everything you need to integrate rIDP into your applications

Quick Start

Get up and running in 5 minutes

OAuth 2.0

Understanding the flow

API Reference

Complete endpoint documentation

Examples

Code samples & tutorials

rIDP Base URL

All API endpoints use this base URL:

http://devas.ridp.ovh/v1

Getting Started

1. Create an Application

First, create a new application in this developer portal to get your OAuth credentials:

Create Application

2. Get Your Credentials

After creating your application, you'll receive:

  • Client ID - Public identifier for your application
  • Client Secret - Keep this confidential! Never expose it in client-side code.

3. Configure Your Redirect URI

When creating your application, you must specify the redirect URI(s) where users will be sent after authentication. This must exactly match the URI you use in your OAuth requests.

4. Available Scopes

Request the following scopes to access user information:

Scope Description
openid Required for OpenID Connect. Returns the user's unique identifier (sub).
profile Access to user's name and profile information.
email Access to user's email address.

5. Integrate in Your Application

Add a "Login with rIDP" button that redirects users to the authorization endpoint: 

// Redirect user to rIDP authorization endpoint
const authUrl = `http://devas.ridp.ovh/v1/oauth/authorize?` +
  `response_type=code&` +
  `client_id=YOUR_CLIENT_ID&` +
  `redirect_uri=${encodeURIComponent('https://yourapp.com/callback')}&` +
  `scope=openid profile email&` +
  `state=${generateRandomState()}`;

window.location.href = authUrl;

OAuth 2.0 Authorization Flow

Authorization Code Flow

The most secure flow for web applications with server-side code.

  1. Redirect to Authorization Endpoint
    GET /authorize
  2. User Authenticates and Consents

    User logs in and approves your application's access request

  3. Receive Authorization Code

    User is redirected back with a temporary code

  4. Exchange Code for Tokens
    POST /token
  5. Use Access Token

    Make API calls with the access token

Security Note: Never expose your Client Secret in client-side code. For Single Page Applications, use PKCE (Proof Key for Code Exchange).

API Reference

Authorization Endpoint

GET /oauth/authorize

Initiates the OAuth 2.0 authorization flow.

Parameters:

Parameter Required Description
response_type Yes Must be "code"
client_id Yes Your application's client ID
redirect_uri Yes Registered callback URL
scope No Space-separated list of scopes
state Recommended CSRF protection token

Token Endpoint

POST /oauth/token

Exchange authorization code for access tokens, or refresh an existing token.

Parameters (Authorization Code):

Parameter Required Description
grant_type Yes "authorization_code" or "refresh_token"
code Yes* Authorization code received (*required for authorization_code grant)
refresh_token Yes* Refresh token (*required for refresh_token grant)
client_id Yes Your application's client ID
client_secret Yes Your application's client secret
redirect_uri Yes* Same URI used in authorization (*required for authorization_code grant)

Content-Type: Requests must use application/x-www-form-urlencoded

UserInfo Endpoint

GET /oauth/userinfo

Retrieve information about the authenticated user.

Headers:

Header Required Description
Authorization Yes Bearer {access_token}

Response:

{
  "sub": "user-unique-id",
  "email": "user@example.com",
  "name": "John Doe",
  "picture": "https://..."
}

Code Examples

Step 1: Redirect to Login

// Configuration
const CLIENT_ID = 'your-client-id';
const REDIRECT_URI = 'https://yourapp.com/callback';
const IDP_BASE_URL = 'http://devas.ridp.ovh/v1';

// Generate random state for CSRF protection
function generateState() {
  return crypto.randomUUID();
}

// Redirect user to rIDP login
function login() {
  const state = generateState();
  sessionStorage.setItem('oauth_state', state);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'openid profile email',
    state: state
  });

  window.location.href = `${IDP_BASE_URL}/oauth/authorize?${params}`;
}

Step 2: Handle Callback (Server-side)

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

  // Verify state matches
  if (state !== req.session.oauth_state) {
    return res.status(400).send('Invalid state');
  }

  // Exchange code for tokens
  const tokenResponse = await fetch('http://devas.ridp.ovh/v1/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,  // Keep secret on server!
      redirect_uri: REDIRECT_URI
    })
  });

  const tokens = await tokenResponse.json();
  // tokens contains: access_token, refresh_token, expires_in

  // Get user info
  const userResponse = await fetch('http://devas.ridp.ovh/v1/oauth/userinfo', {
    headers: {
      'Authorization': `Bearer ${tokens.access_token}`
    }
  });

  const user = await userResponse.json();
  // user contains: sub, email, name, etc.

  // Create session and redirect
  req.session.user = user;
  res.redirect('/dashboard');
});

Flask Example

import secrets
import requests
from flask import Flask, redirect, request, session, url_for

app = Flask(__name__)
app.secret_key = 'your-secret-key'

CLIENT_ID = 'your-client-id'
CLIENT_SECRET = 'your-client-secret'
REDIRECT_URI = 'http://localhost:5000/callback'
IDP_BASE_URL = 'http://devas.ridp.ovh/v1'

@app.route('/login')
def login():
    """Redirect user to rIDP for authentication"""
    state = secrets.token_urlsafe(32)
    session['oauth_state'] = state

    params = {
        'response_type': 'code',
        'client_id': CLIENT_ID,
        'redirect_uri': REDIRECT_URI,
        'scope': 'openid profile email',
        'state': state
    }
    auth_url = f"{IDP_BASE_URL}/oauth/authorize?" + "&".join(
        f"{k}={v}" for k, v in params.items()
    )
    return redirect(auth_url)

@app.route('/callback')
def callback():
    """Handle OAuth callback from rIDP"""
    # Verify state
    if request.args.get('state') != session.get('oauth_state'):
        return 'Invalid state', 400

    code = request.args.get('code')

    # Exchange code for tokens
    token_response = requests.post(
        f'{IDP_BASE_URL}/oauth/token',
        data={
            'grant_type': 'authorization_code',
            'code': code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI
        },
        headers={'Content-Type': 'application/x-www-form-urlencoded'}
    )
    tokens = token_response.json()

    # Get user info
    user_response = requests.get(
        f'{IDP_BASE_URL}/oauth/userinfo',
        headers={'Authorization': f"Bearer {tokens['access_token']}"}
    )
    user = user_response.json()

    session['user'] = user
    return redirect('/dashboard')

Step 1: Exchange Code for Token

curl -X POST http://devas.ridp.ovh/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

# Response:
# {
#   "access_token": "eyJ...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "..."
# }

Step 2: Get User Info

curl http://devas.ridp.ovh/v1/oauth/userinfo \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response:
# {
#   "sub": "user-id",
#   "email": "user@example.com",
#   "name": "John Doe"
# }

Refresh Token

curl -X POST http://devas.ridp.ovh/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"