API Credentials: What You Issue vs What You Hold

An API credential is proof of identity on a request

An API credential is whatever a caller presents so a server will treat the request as authenticated: an API key, a bearer token, a username and password, a signed JWT, an OAuth access token. The formats differ. The job does not. Someone or something is claiming an identity, and the other side has to decide whether that claim is good.

In industry talk, “the credentials” usually means the vendor secret sitting in an environment variable, a 1Password vault, or a Slack thread from last quarter. That is one object doing two jobs: it identifies the caller and it unlocks the upstream account. Those jobs should not share a secret.

Two jobs, two objects

The useful split is which side of the call you are on.

A target credential is the vendor secret the gateway holds: the Stripe key, the CRM token, the weather API header. RequestRocket attaches it only after policy allows the call. Callers never receive it. GET on the credential does not return the plaintext. Rotation is writing a new record and pointing the proxy at it, not editing a field.

A proxy credential is what you issue. It is the key, bearer token, or JWT an app, agent, or teammate presents to the gateway. Compromise of that credential is compromise of that caller’s grant, not of the vendor account.

That is the whole model. One secret you hold. One secret you issue. They are different rows.

Whether a given scheme is a good default is argued elsewhere: in defence of API keys, API key authentication best practices, and JWT vs API key auth for M2M. This post is the object that holds the scheme.

What the record actually stores

A RequestRocket credential is a first-class record, not a string in config. Create one with POST /clients/{clientId}/credentials. Four fields are always required: credentialType, credentialAuthType, credentialName, and credentialRegion. The fifth, credentialSecret, is write-once.

{
  "credentialType": "target",
  "credentialAuthType": "key",
  "credentialName": "weather-api-key",
  "credentialRegion": "us-east-1",
  "credentialSecret": {
    "key": "X-API-Key",
    "value": "sk_live_4c9a1f7b2e8d",
    "addToHeader": true
  }
}

• credentialType is target or proxy. That is the split above. There is no third kind.
• credentialAuthType is the scheme on the wire: key, bearer, basic, oauth2, jwt, jwtVerify, jwtSigned, custom, customToken, or none. The shape of credentialSecret follows the type. A key secret needs key (the header or query name), value (the secret), and addToHeader.
• credentialRegion pins the encrypted secret to a data plane region. The secret lives there, not in the management API. You configure the record through the control plane; the bytes sit with the data plane that will use them.
• credentialSecret is accepted on create and then gone. Subsequent PUT can change credentialName and credentialNotes. It cannot change the secret. If the value is wrong, you create a replacement.

Proxy key credentials have a hard constraint the target side does not: inbound authentication to the gateway only accepts the Authorization header. Set key: "Authorization" (and a prefix if you want Bearer or Api-Key ). Put the vendor’s odd header name on the target credential. That is the point of having two records.

The gateway does the hard work, not your code

Static secrets (key, bearer, basic) are the simplest case: the gateway attaches a fixed value. The other credentialAuthType values move real operational work off your stack:

• oauth2 – the gateway runs the OAuth2 client-credentials or authorization-code flow, caches the access token, and refreshes it before expiry. Your caller never sees the client_secret or the refresh token.
• customToken – the gateway calls a vendor’s non-standard login endpoint, extracts the token from the response (you configure the JSON path and expiry format), caches it, and re-fetches when it lapses. Every vendor that invented its own auth dance becomes a single config record.
• jwtSigned – the gateway holds a private key and mints a fresh, signed JWT on every request. You configure the claims template with variables like {{now}} and {{now+3600}}; the gateway does the signing. This covers Snowflake key-pair auth, Google service accounts, Salesforce JWT bearer, and any RS256/ES256 service identity.
• jwtVerify – a proxy credential type. Instead of comparing a static key, the gateway verifies the caller’s JWT signature against a JWKS endpoint, checks exp, iss, aud, and optional claims. Short-lived, rotatable inbound auth without writing verification code.

The full survey of methods covers the wire-level detail. The point here is that a credential record is not just a place to paste a secret – it is a declaration of what work the gateway should do on every request.

Credentials carry their own policy

A credential is not only an identity record. It can carry rules, filters, meters, and overrides of its own.

• Credential rules scope what any proxy using this credential can reach, independent of the proxy’s own rule set. An allow rule on a credential does not override a deny on the proxy. Both must agree.
• Credential filters apply response-body operations (retain or destroy fields, filter array rows) whenever this credential is used, regardless of which proxy.
• Credential meters enforce rate limits per credential – useful when one target credential is shared across several proxies and you need a single budget.

These are distinct from proxy-level rules, filters, and meters. They allow you to set policy once on the credential and have it follow the identity wherever it is used.

What an API credential is not

It is not a console login. Humans who need the management UI are members, invited with a role. An agent that needs to call a proxy gets a proxy credential. Mixing those – pasting a vendor key into an agent’s env because “the teammate already has it in 1Password” – is how one secret becomes twelve.

It is not the scheme itself. An API key is one credentialAuthType. A JWT is another. The survey of methods is in API authentication methods explained; the mechanics of a key are in What is an API key.

It is not a secrets manager entry you hand to every process. Vault and Secrets Manager store the value. They do not stop every caller from holding a working copy, and they do not scope what each caller may do with it. A credential record scopes by design: it binds to a proxy, which has rules, filters, and meters.

Next steps

Create one target credential for the vendor secret and one proxy credential per caller. Bind them on a proxy with a deny-by-default rule set. How to issue access without handing over the vendor key is in How to share API credentials without the vendor key. Configure both in the credentials guide. RequestRocket is runtime access control for AI agents and apps calling APIs you don’t own – every call gets a least-privilege credential, a policy check, and an audit record, with no code changes.