Skip to main content
This guide walks through the shortest path to a working Riftmap integration: sign up, connect an org, run a scan, mint an API key, and resolve a repo by URL.

​
1. Create an account

Sign up at app.riftmap.dev/register. The free plan includes one workspace, up to 15 repos, and one connected org — enough to validate the integration end‑to‑end before deciding whether a paid plan makes sense.

​
2. Connect a GitHub or GitLab org

After registration the onboarding wizard prompts you to connect your first org. Two paths:
  • OAuth (one click) — works for GitLab today and for GitHub orgs where your linked account already has repo scope.
  • Personal Access Token (PAT) — recommended for GitHub. A fine‑grained PAT with Contents: Read‑only + Metadata: Read‑only is enough; classic PATs need repo + read:org.
Riftmap stores the token encrypted at rest with Fernet and never makes a write call against your org.

​
3. Trigger the first scan

Once the org is connected, Riftmap kicks off an initial scan automatically. A full scan of a small org typically completes in under a minute; larger orgs scale roughly with (repo count) × (avg manifest count). You can also trigger a scan manually:

​
4. Create a workspace API key

In the app: Settings → API keys → Create new key. The raw key is shown once — copy it into your secret manager immediately. Keys are workspace‑scoped, so they never need a workspace_id parameter. Keys look like rfm_live_<random>. Use them as either header:
See Authentication for the full header conventions.

​
5. Make your first call

The most common agent entry point is “I have a clone URL — what does Riftmap know about this repo?”:
Sample response (truncated):
The freshness fields (last_scanned_at, last_commit_sha, last_activity_at, archived) appear on every repo response. Agents should compare last_activity_at to last_scanned_at to decide whether the data is fresh enough to act on.

​
Next step

Most agent integrations need more than a single repo lookup. The recommended pattern for hydrating context in one round‑trip is documented in Agent integration → Overview.