# AI use cases for Synapass (ShadowSafin/Synapass)

Repo: [ShadowSafin/Synapass](https://github.com/ShadowSafin/Synapass) | Use cases: 4 | Page: https://dedupedai.com/use-cases/shadowsafin-synapass/

Synapass is an open-source OpenAI-compatible gateway and control plane that routes each AI request to a provider under policy, handles failover, caching, budgets, and request tracing.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Send all app AI calls through one OpenAI-style endpoint: https://dedupedai.com/use-cases/shadowsafin-synapass/one-endpoint-for-many-ai-providers/
- Trace which provider and policy handled a bad AI answer: https://dedupedai.com/use-cases/shadowsafin-synapass/explain-why-a-request-went-where-it-did/
- Set spending limits so one team cannot run up the AI bill: https://dedupedai.com/use-cases/shadowsafin-synapass/cap-ai-spend-per-team-with-budgets/
- Run the gateway as a native service on a Linux server: https://dedupedai.com/use-cases/shadowsafin-synapass/run-gateway-natively-on-a-linux-server/

## How to send all app AI calls through one OpenAI-style endpoint with Synapass

Repo: [ShadowSafin/Synapass](https://github.com/ShadowSafin/Synapass) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Point existing OpenAI SDK code at one gateway that routes to several providers with failover.

**Who it is for:** A developer whose services each call a different AI provider with separate error handling and routing code.

**The problem:** Each service carries its own provider integration, so failures and model choices are handled inconsistently and one upstream outage can stop the app.

**The outcome:** Applications call one OpenAI-compatible URL, and the gateway picks the provider, fails over when needed, and reports which provider answered.

### Steps

1. Run `./scripts/deploy.sh` from the cloned repo root, or the one-line installer for your OS from the README.
2. Add a provider key such as OPENAI_API_KEY to `.env`, then run `./scripts/deploy.sh` again.
3. Create a tenant key with a POST to /admin/v1/keys using the admin key, as shown in the README example request.
4. Send a chat request to `curl -s $GATEWAY/v1/chat/completions` with the tenant key as the Bearer token.
5. Read the `synapass` block in the response to confirm the answering provider and whether fallback_used is true.

### Prompt to paste into your agent

```text
Using the ShadowSafin/Synapass repo, deploy the stack with ./scripts/deploy.sh, mint a tenant key, and send one chat completion to /v1/chat/completions for the model <model_name>. Report the synapass.provider and synapass.fallback_used values. Verify that the HTTP status is 200 and the response contains a choices array.
```

### Caveat

The README says the stack boots without a provider key and reports providers as unconfigured until one is added, so inference calls will fail until you add a key.

Risk, credentials: The admin key and tenant keys grant access to every provider you configure, so store them in `.env` or a secret manager and never commit them.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/shadowsafin-synapass/one-endpoint-for-many-ai-providers/

## How to trace which provider and policy handled a bad AI answer with Synapass

Repo: [ShadowSafin/Synapass](https://github.com/ShadowSafin/Synapass) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Look up a request ID to see the routing reason, policy verdict, and answering provider.

**Who it is for:** An engineer investigating a complaint about a wrong or slow AI answer and needing to know which model produced it.

**The problem:** Without a central record, it is hard to tell which model, provider, or fallback produced a specific answer.

**The outcome:** The engineer gets the routing explanation for one request ID, including the provider that actually answered.

### Steps

1. Copy the `request_id` from the `synapass` block of the response that needs review.
2. Run `curl -s $GATEWAY/admin/v1/requests/<request_id>/explain -H "Authorization: Bearer $SYNAPASS_ADMIN_KEY"`. (inferred, check the README)
3. Check the policy verdict, cache decision, and routing reason in the explain output.
4. Compare `provider` with `requested_model` and `routed_model` in the original response to confirm what answered.

### Prompt to paste into your agent

```text
In the ShadowSafin/Synapass repo, call GET /admin/v1/requests/<request_id>/explain with the admin key and summarize the routing reason and the answering provider. Verify that the summary names the same provider as the synapass.provider field in the original response.
```

### Caveat

The explain endpoint is described in the README, but its exact response fields are not shown there, so check the output format against the documentation before you build automation on it.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/shadowsafin-synapass/explain-why-a-request-went-where-it-did/

## How to set spending limits so one team cannot run up the AI bill with Synapass

Repo: [ShadowSafin/Synapass](https://github.com/ShadowSafin/Synapass) | Difficulty: Advanced | Time: 45 minutes | Basis: From the README

Use tenant keys with budgets, rate limits, and per-request ceilings to control AI costs.

**Who it is for:** A team lead or platform owner who must keep AI spend within a monthly amount and stop runaway loops.

**The problem:** A runaway loop or heavy workload can produce a large bill that nobody notices until it arrives.

**The outcome:** Each tenant has its own key and limits, so calls are blocked before they exceed the ceiling or budget.

### Steps

1. Run `./scripts/deploy.sh` to start the stack, then sign in to the dashboard at the URL the script prints.
2. Create one tenant per team in the dashboard and set daily or monthly budgets and token or request rate limits.
3. Mint a separate key per tenant with `curl -s $GATEWAY/admin/v1/keys -H "Authorization: Bearer $SYNAPASS_ADMIN_KEY"` and the tenant id. (inferred, check the README)
4. Set a per-request cost ceiling in a policy, then run `bash scripts/smoke.sh` to check the stack end to end.

### Prompt to paste into your agent

```text
In the ShadowSafin/Synapass repo, create a tenant named <team_name> with a daily budget and a rate limit through the dashboard or admin API, then mint one key for it. Report the tenant id and confirm that a request above the configured ceiling is refused. Verify the refusal in the response before reporting success.
```

### Caveat

The README names budgets and ceilings as features but does not show the exact dashboard steps or limit fields, so confirm the settings in the Dashboard documentation before you rely on them.

Risk, credentials: Tenant keys are bearer credentials, so distribute each one only to the team it belongs to and rotate it if it leaks.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/shadowsafin-synapass/cap-ai-spend-per-team-with-budgets/

## How to run the gateway as a native service on a Linux server with Synapass

Repo: [ShadowSafin/Synapass](https://github.com/ShadowSafin/Synapass) | Difficulty: Advanced | Time: 60 minutes | Basis: From the README

Build and install Synapass without Docker, then run it under systemd.

**Who it is for:** A systems administrator who runs services on a Linux host and does not want a container runtime.

**The problem:** Teams that avoid Docker still need the same gateway, dashboard, and migrations on their own hosts.

**The outcome:** Gateway and dashboard run natively, supervised by systemd units or the foreground supervisor.

### Steps

1. Clone the repo and run `make build` from the repo root.
2. Run `synapass native install` to create templates, build, and apply migrations.
3. Run `synapass native up` for a foreground supervisor, or install the units from `deploy/systemd/` for production.
4. Check readiness with `curl -sf http://127.0.0.1:8080/ready`.

### Prompt to paste into your agent

```text
In the ShadowSafin/Synapass repo, build with make build, install with synapass native install, and start with synapass native up on <host>. Report the output of curl -sf http://127.0.0.1:8080/ready. Verify that the readiness check succeeds before reporting the service as running.
```

### Caveat

The README gives native steps for Linux but names PostgreSQL, Redis, ClickHouse, and NATS as required services, so you must provision those before the native install can work.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/shadowsafin-synapass/run-gateway-natively-on-a-linux-server/