Authentication

The RedCore SDK supports three authentication methods. Choose the one that matches your application architecture and security requirements.

Method Comparison

Method	Security Level	Complexity	Recommended For
API Key	Medium	Low	Server-to-server integrations, scripts, CI/CD pipelines.
OAuth 2.0	High	Medium	Web apps and mobile apps acting on behalf of an end user.
SAML 2.0	Enterprise	High	Corporate SSO environments (Okta, Azure AD, Google Workspace).

Important

Store all credentials — API keys, client secrets, SAML private keys — in environment variables or a dedicated secrets manager. Never commit them to source control.

API Key Authentication

API keys are long-lived static credentials scoped to your RedCore project. They are the simplest authentication method and are recommended for backend services that do not operate on behalf of individual users.

Obtaining an API Key

Log in to the RedCore Dashboard.
Navigate to Settings → API Keys.
Click Generate New Key, choose a descriptive name, and select the required scopes.
Copy the key immediately — it is shown only once.

Warning

API keys cannot be recovered after creation. If lost, revoke the old key and generate a new one. See API Key Rotation for the safe rotation procedure.

Using an API Key

Python — API key initialization

import os
from redcore import Client

client = Client(api_key=os.environ["REDCORE_API_KEY"])

Node.js — API key initialization

const { RedcoreClient } = require("@redcore/sdk");

const client = new RedcoreClient({
  apiKey: process.env.REDCORE_API_KEY,
});

cURL — API key in the Authorization header

curl -X GET "https://api.redcore.com/v1/users" \
  -H "Authorization: Bearer $REDCORE_API_KEY" \
  -H "Accept: application/json"

API Key Rotation

Rotate keys periodically (recommended: every 90 days) and immediately after any suspected exposure.

Safe zero-downtime key rotation

# 1. Generate the new key in the Dashboard and set it in the new env var
export REDCORE_API_KEY_NEW=rk_live_newkey...

# 2. Deploy the new key to your application (rolling deploy / blue-green)
# 3. Confirm all traffic is using the new key (check logs / metrics)
# 4. Revoke the old key in the Dashboard

Note

Both the old and new key are valid simultaneously during the rotation window, so there is no service interruption.

OAuth 2.0 Authentication

OAuth 2.0 is required when your application acts on behalf of an end user and needs to access resources scoped to that user's account.

Hint

Use the Authorization Code + PKCE flow for web and mobile apps. Use Client Credentials for pure machine-to-machine communication.

OAuth 2.0 Flow Diagram

        sequenceDiagram
  participant User   as End User
  participant App    as Your App
  participant Auth   as RedCore Auth Server
  participant API    as RedCore API

  User->>App:  Click "Connect with RedCore"
  App->>Auth:  Redirect → /oauth/authorize?client_id=...&code_challenge=...
  Auth->>User: Show consent screen
  User->>Auth: Grant permission
  Auth->>App:  Redirect → /callback?code=AUTH_CODE
  App->>Auth:  POST /oauth/token (code + code_verifier)
  Auth-->>App: { access_token, refresh_token, expires_in: 3600 }
  App->>API:   GET /v1/users  (Authorization: Bearer access_token)
  API-->>App:  200 OK — user data
  Note over App,Auth: After 3 600 s the access_token expires…
  App->>Auth:  POST /oauth/token (grant_type=refresh_token)
  Auth-->>App: { new access_token, new refresh_token }

Step 1 — Register Your Application

Register at developer.redcore.com to obtain your client_id and client_secret, and to configure your allowed redirect URIs.

Step 2 — Initialize the Client

Python — OAuth 2.0 initialization

import os
from redcore import Client

client = Client(
    client_id=os.environ["REDCORE_CLIENT_ID"],
    client_secret=os.environ["REDCORE_CLIENT_SECRET"],
)
# The SDK automatically requests and caches a token on the first API call.

Node.js — OAuth 2.0 initialization

const { RedcoreClient } = require("@redcore/sdk");

const client = new RedcoreClient({
  clientId:     process.env.REDCORE_CLIENT_ID,
  clientSecret: process.env.REDCORE_CLIENT_SECRET,
});

Step 3 — Handle Token Refresh

The SDK refreshes the access token automatically before it expires. If you need to persist tokens across restarts (e.g., in a long-running server), implement the on_token_refreshed callback to save the new tokens to your storage layer.

Python — persisting refreshed tokens

import json, os
from redcore import Client

def save_tokens(token_data: dict) -> None:
    """Callback invoked whenever the SDK refreshes a token pair."""
    with open(".tokens.json", "w") as f:
        json.dump(token_data, f)

# Load previously persisted tokens (if any)
stored = {}
if os.path.exists(".tokens.json"):
    with open(".tokens.json") as f:
        stored = json.load(f)

client = Client(
    client_id=os.environ["REDCORE_CLIENT_ID"],
    client_secret=os.environ["REDCORE_CLIENT_SECRET"],
    access_token=stored.get("access_token"),
    refresh_token=stored.get("refresh_token"),
    on_token_refreshed=save_tokens,
)

Warning

Access tokens expire after 60 minutes. Refresh tokens expire after 30 days of inactivity. If the refresh token expires, the user must re-authenticate from scratch.

Token Lifetimes

Token Type	TTL	Rotation
Access Token	3 600 s (1 hour)	Issued on every token request.
Refresh Token	30 days (sliding)	Rotated on every refresh — old token is immediately invalidated.

SAML 2.0 Authentication

SAML 2.0 enables your organization's Identity Provider (IdP) — such as Okta, Azure Active Directory, or Google Workspace — to act as the authority for user authentication. RedCore acts as the Service Provider (SP).

Note

SAML is available on Enterprise plans only. Contact enterprise@redcore.com to enable it for your organization.

SAML Flow Overview

        sequenceDiagram
  participant User as End User
  participant SP   as RedCore (Service Provider)
  participant IdP  as Your IdP (Okta / Azure AD)

  User->>SP:  Access protected resource
  SP->>User:  Redirect → IdP login page
  User->>IdP: Authenticate (username + password / MFA)
  IdP->>SP:   POST SAMLResponse (signed XML assertion)
  SP->>SP:    Validate signature & extract attributes
  SP->>User:  Issue session / access token

Configuration

Setting	Description
SP Entity ID	`https://auth.redcore.com/saml/metadata`
ACS URL	`https://auth.redcore.com/saml/acs`
Metadata URL	`https://auth.redcore.com/saml/metadata.xml`
NameID format	`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
Signature algorithm	RSA-SHA256

Provide these values to your IdP administrator when setting up the RedCore application in your IdP's dashboard.

Python — SAML initialization using an IdP-issued assertion

from redcore import Client

# Exchange a SAML assertion for a RedCore access token
client = Client.from_saml_assertion(
    assertion=idp_saml_response_xml,   # raw XML string from IdP POST
    client_id=os.environ["REDCORE_CLIENT_ID"],
)

Authentication Errors

Error / Status Code	Meaning and fix
`401 INVALID_TOKEN`	Token is malformed or does not exist. Re-acquire a fresh token.
`401 TOKEN_EXPIRED`	Access token has passed its TTL. The SDK retries with the refresh token automatically; if this still fails, re-authenticate.
`403 INSUFFICIENT_SCOPE`	Token lacks the required scope. Request a token with the missing scope(s) added.
`AuthenticationError` (SDK)	Raised when the server returns 401. Inspect `exc.code` for the specific error code.
`PermissionError` (SDK)	Raised when the server returns 403.