Getting Started with the RedCore SDK

The RedCore SDK is the fastest way to integrate with the RedCore platform. It is available for Python, Node.js, Go, and Java, wraps every REST endpoint in a typed, idiomatic interface, and handles token refresh and retries automatically — so you focus on your product, not on HTTP plumbing.

How the SDK Fits In

        flowchart LR
  App["Your Application"]
  SDK["RedCore SDK"]
  Auth["Auth Server\n(OAuth 2.0)"]
  API["RedCore REST API"]

  App  -->|"SDK method call"| SDK
  SDK  -->|"POST /oauth/token\n(auto-refresh)"| Auth
  Auth -->|"access_token"| SDK
  SDK  -->|"HTTPS + Bearer token"| API
  API  -->|"JSON response"| SDK
  SDK  -->|"typed object / exception"| App

The SDK manages token acquisition and renewal transparently — you never touch raw HTTP or handle token expiry manually.

Prerequisites

Requirement	Details
RedCore account	An active project in the RedCore Dashboard.
Credentials	An API Key or OAuth 2.0 `client_id` + `client_secret` pair.
Runtime	Python ≥ 3.8 · Node.js ≥ 18 · Go ≥ 1.21 · Java ≥ 17

Installation

Python

We recommend using a virtual environment to isolate dependencies.

Python — install via pip

python3 -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install redcore-sdk

Node.js

Node.js — install via npm

npm install @redcore/sdk

Go

Go — add the module

go get github.com/redcore/go-sdk@latest

Java (Maven)

pom.xml — Maven dependency

<dependency>
  <groupId>com.redcore</groupId>
  <artifactId>sdk</artifactId>
  <version>2.1.0</version>
</dependency>

Configuration

The SDK client accepts the following options. Supplying credentials via environment variables is strongly recommended so they never appear in source code or version control.

Client configuration options
Option	Required	Description
`api_key`	Yes *	Static API key. Use for server-to-server calls without a user context.
`client_id`	Yes *	OAuth 2.0 client identifier. Required when using the OAuth flow.
`client_secret`	Yes *	OAuth 2.0 client secret. Required when using the OAuth flow.
`base_url`	No	Override the API root. Default: `https://api.redcore.com/v1`.
`timeout`	No	Request timeout in seconds. Default: `30`.
`max_retries`	No	Automatic retries on 5xx responses. Default: `3`.
`environment`	No	`production` (default) or `staging`.

* Supply either api_key or the client_id + client_secret pair.

Important

Never hardcode credentials in source files or commit them to version control. Use environment variables or a secrets manager such as AWS Secrets Manager or HashiCorp Vault.

.env — recommended credential pattern

REDCORE_API_KEY=rk_live_abc123...
REDCORE_BASE_URL=https://api.redcore.com/v1
REDCORE_TIMEOUT=30

Initializing the Client

Python

app.py — read credentials from the environment

import os
from redcore import Client

client = Client(
    api_key=os.environ["REDCORE_API_KEY"],
    base_url=os.environ.get("REDCORE_BASE_URL"),
    timeout=int(os.environ.get("REDCORE_TIMEOUT", 30)),
)

Node.js

app.js — read credentials from the environment

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

const client = new RedcoreClient({
  apiKey:  process.env.REDCORE_API_KEY,
  timeout: parseInt(process.env.REDCORE_TIMEOUT ?? "30", 10),
});

Go

main.go — functional options pattern

import (
    "os"
    "github.com/redcore/go-sdk/redcore"
)

client := redcore.NewClient(
    redcore.WithAPIKey(os.Getenv("REDCORE_API_KEY")),
    redcore.WithTimeout(30),
)

Your First API Call

Retrieve your own profile to confirm the SDK and credentials are correctly configured.

Python — smoke test with error handling

from redcore.exceptions import AuthenticationError, RedcoreAPIError

try:
    me = client.users.get_me()
    print(f"Connected as: {me.name} <{me.email}>")
except AuthenticationError:
    print("Invalid or expired API key — check REDCORE_API_KEY.")
except RedcoreAPIError as exc:
    print(f"API error {exc.status_code}: {exc.message}")

Node.js — smoke test with error handling

try {
  const me = await client.users.getMe();
  console.log(`Connected as: ${me.name} <${me.email}>`);
} catch (err) {
  if (err.status === 401) console.error("Invalid API key.");
  else console.error(`API error ${err.status}: ${err.message}`);
}

Tip

Add this snippet as a health-check step in your CI pipeline to catch credential drift before it reaches production.

Error Handling

Every SDK method raises (or rejects with) a typed exception rather than returning raw HTTP objects. All exceptions inherit from RedcoreError so you can catch selectively or broadly.

Exception	When it is raised
`AuthenticationError`	API key or token is missing, invalid, or expired (HTTP 401).
`PermissionError`	Credentials lack the required scope (HTTP 403).
`NotFoundError`	The requested resource does not exist (HTTP 404).
`ValidationError`	Request body failed server-side validation (HTTP 400 / 422).
`RateLimitError`	Rate limit exceeded (HTTP 429). Carries a `retry_after` attribute.
`RedcoreAPIError`	Any other 4xx / 5xx response. Carries `status_code` and `message`.
`NetworkError`	Connection timeout or DNS failure (no HTTP response received).

Python — graceful retry on rate-limit and transient errors

import time
from redcore.exceptions import RateLimitError, RedcoreAPIError

def safe_get_user(client, user_id: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            return client.users.get(user_id)
        except RateLimitError as exc:
            time.sleep(exc.retry_after)
        except RedcoreAPIError as exc:
            if exc.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise
    raise RuntimeError("Max retries exceeded.")

Next Steps

Authentication	API Key, OAuth 2.0, and SAML authentication in depth.
API Endpoints Reference	Full method reference with request / response schemas.
OAuth 2.0 Authentication	REST-level OAuth 2.0 token lifecycle and revocation.
Errors & Status Codes	Complete error-code catalogue and retry guidance.