Skip to main content

Authentication

The Filedgr partner API authenticates every request with a key and secret pair, sent as two headers. There is no token exchange, no OAuth flow, and no request signing — and there are no anonymous endpoints.

HeaderValue
x-api-keyYour API key (UUID)
x-api-secretYour API secret (UUID)
curl "https://api.filedgr.network/vaults" \
  -H "x-api-key: $FILEDGR_API_KEY" \
  -H "x-api-secret: $FILEDGR_API_SECRET"

Both headers are required on every route. The secret is compared in constant time, so a mismatch leaks nothing about how close the value was.

Server-to-server only

x-api-key and x-api-secret are not in the API's CORS Access-Control-Allow-Headers allowlist, so browser requests fail preflight. Call this API from your backend, and never ship these credentials to a client application.

Base URLs​

EnvironmentBase URL
Productionhttps://api.filedgr.network
Testhttps://api.test.filedgr.network
Developmenthttps://api.dev.filedgr.network

Environments are separate deployments, so a key is implicitly scoped to the host that issued it. A production key will not authenticate against the test host.

Credential format​

Both values are UUID4s generated server-side. You cannot supply your own pair — the credential endpoint deliberately refuses an API key submitted by a client, so the key and secret are always platform-generated.

# .env — both values are UUIDs
FILEDGR_API_KEY=3f8c1d2e-0a5b-4c7d-9e11-6b2a4f8c0d13
FILEDGR_API_SECRET=b71e5a94-2c3f-48d6-8a0e-1f9c7d4b2e60

A value that is not a well-formed UUID is rejected with 422 before the key is ever looked up.

Obtaining credentials​

From the web app, sign in and issue a key from your account's API key settings. This calls POST /credentials/api-keys, which takes no request body and returns the new credential.

Copy the secret now

The plaintext secret is returned once, on the creation response, and is stripped from every other read path. If you lose it, issue a new key — it cannot be recovered.

Note that key issuance is a web-app operation. The partner API itself exposes no endpoint that creates, lists, rotates or revokes credentials.

Key scope​

An API key is a single credential that carries the full authority of the user who created it. What a key can reach is decided by the vault, stream and asset permissions held by its owner, rather than by anything stored on the key itself.

Scoped keys — read-only credentials and per-key permission sets — are on the roadmap. Until they land, isolate access by using a key belonging to a user with only the permissions that integration needs.

Credential lifetime​

API keys do not expire and there is nothing to refresh. A key stays valid until the credential is removed.

Rotation​

  1. Issue a new API key
  2. Update the credentials in your production configuration
  3. Verify traffic is flowing on the new key
note

Self-service key revocation is coming. For now, contact Filedgr support to retire a credential.

Your API key is the principal​

The key identifies the caller. Path segments that name a user are always resolved to the key holder:

GET /users/{user_id}/favorites/type/VAULT returns your favorites regardless of the user_id in the path.

The same applies to /users/{user_id}/entities and /users/{user_id}/invitations. You cannot read or modify another user's data by changing the id, and you should not build logic that assumes otherwise.

Tenancy: entities​

Everything you create — vaults, assets, webhooks, credits — belongs to an entity, not to a user directly. Your API key resolves to a user, and that user's entity owns the data.

A key that resolves to no entity returns 404, not 403. Entity scoping is also why 404 is the standard response for a resource that exists but is not yours: the API does not distinguish "not found" from "not yours", by design.

Authentication errors​

Authentication failures do not use the standard {"error", "message"} envelope — they return the framework's {"detail": ...} shape.

Missing header — x-api-key or x-api-secret absent (403):

{ "detail": "Not authenticated" }

Malformed credential — either header is not a valid UUID (422):

{ "detail": [{ "loc": ["header", "x-api-key"], "msg": "Input should be a valid UUID" }] }

Wrong secret (403):

{ "detail": "Could not validate API KEY" }

Authorization failures — you are authenticated but not permitted — use the normal envelope with "error": "ForbiddenError".

Handling rejections​

A 403 from this API means the credentials themselves were rejected. Retrying will not help, and there is no token to refresh, so fail fast rather than looping:

async function filedgrFetch(path, options = {}) {
  const res = await fetch(`https://api.filedgr.network${path}`, {
    ...options,
    headers: {
      'x-api-key': process.env.FILEDGR_API_KEY,
      'x-api-secret': process.env.FILEDGR_API_SECRET,
      ...options.headers,
    },
  });

  // Bad credentials — retrying will not help.
  if (res.status === 403) throw new Error('Filedgr: credentials rejected');
  return res;
}

Storing credentials​

  • Keep the key and secret in environment variables or a secrets manager, never in source control.
  • Never expose them to a browser or mobile client — see the CORS note above.
  • Use a distinct key per environment and per integration, so one can be retired independently.

Next steps​