Ryvn API Reference

The Ryvn API allows you to programmatically manage your organizations, environments, services, and deployments. All API endpoints use REST principles and return JSON responses.

Base URL

https://api.ryvn.app

Authentication

The Ryvn API uses OAuth 2.0 client credentials flow for authentication. All API requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-access-token>

Service User Setup

To access the API, you need to create a service user in your organization settings. Navigate to Settings > Service Users and click “Create” to generate your credentials.

This will provide you with:

Client ID: Your unique client identifier
Client Secret: Your secret key for authentication

OAuth Token Exchange

Once you have your service user credentials, you must exchange them for an access token using the OAuth 2.0 client credentials flow. Authentication Endpoint: https://auth.ryvn.app/oauth/v2/token

cURL Example

curl --request POST \
  --url https://auth.ryvn.app/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=openid email profile offline_access urn:zitadel:iam:org:project:id:298766811497774120:aud' \
  --user "$CLIENT_ID:$CLIENT_SECRET"

Response

{
  "access_token": "MtjHodGy4zxKylDOhg6kW90WeEQs2q...",
  "token_type": "Bearer",
  "expires_in": 43199
}

Required Scopes

The following scopes are required for API access:

openid: OpenID Connect authentication
email: Access to email information
profile: Access to profile information
offline_access: Refresh token capability
urn:zitadel:iam:org:project:id:298766811497774120:aud: Project-specific audience scope

Code Examples

Go
Python
JavaScript

package main

import (
    "context"
    "fmt"
    "golang.org/x/oauth2/clientcredentials"
)

func main() {
    config := clientcredentials.Config{
        ClientID: "your-client-id",
        ClientSecret: "your-client-secret",
        TokenURL: "https://auth.ryvn.app/oauth/v2/token",
        Scopes: []string{
            "openid",
            "email",
            "profile",
            "offline_access",
            "urn:zitadel:iam:org:project:id:298766811497774120:aud",
        },
    }

    token, err := config.Token(context.Background())
    if err != nil {
        panic(err)
    }

    fmt.Printf("Access Token: %s\n", token.AccessToken)

}

import requests

def get_access_token(client_id, client_secret):
    url = "https://auth.ryvn.app/oauth/v2/token"

    data = {
        'grant_type': 'client_credentials',
        'scope': 'openid email profile offline_access urn:zitadel:iam:org:project:id:298766811497774120:aud'
    }

    response = requests.post(
        url,
        data=data,
        auth=(client_id, client_secret)
    )

    return response.json()['access_token']

# Usage
access_token = get_access_token('your-client-id', 'your-client-secret')

async function getAccessToken(clientId, clientSecret) {
    const response = await fetch('https://auth.ryvn.app/oauth/v2/token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': `Basic ${btoa(`${clientId}:${clientSecret}`)}`
        },
        body: new URLSearchParams({
            grant_type: 'client_credentials',
            scope: 'openid email profile offline_access urn:zitadel:iam:org:project:id:298766811497774120:aud'
        })
    });
    
    const data = await response.json();
    return data.access_token;
}

// Usage
const accessToken = await getAccessToken('your-client-id', 'your-client-secret');

Using the Access Token

Once you have an access token, include it in the Authorization header for all API requests:

curl -H "Authorization: Bearer your-access-token" https://api.ryvn.app/v1/orgs

Token Expiration

Access tokens expire after the time specified in the expires_in field (typically 12 hours). You will need to request a new token when the current one expires. Consider implementing token caching and automatic refresh in your applications to handle this gracefully.

Overview

Secrets

API Reference

Ryvn API Reference

Base URL

Authentication

Service User Setup

OAuth Token Exchange

cURL Example

Response

Required Scopes

Code Examples

Using the Access Token

Token Expiration

Overview

Secrets

​Ryvn API Reference

​Base URL

​Authentication

​Service User Setup

​OAuth Token Exchange

​cURL Example

​Response

​Required Scopes

​Code Examples

​Using the Access Token

​Token Expiration

Ryvn API Reference

Base URL

Authentication

Service User Setup

OAuth Token Exchange

cURL Example

Response

Required Scopes

Code Examples

Using the Access Token

Token Expiration