Other auth types

Some APIs do not take a plain token. They want each request signed, or they answer with a challenge first. ApiWorkbench does the signing and the challenge handling for seven such schemes. This page lists the fields of each one.

All of them are on the Auth tab under Auth type, and all can be set on a collection or folder and inherited. See Authorization for the basics.

Things they have in common

• Variables. Every field accepts {{variables}}. Keep secrets in an environment and mark them Secret.
• Advanced. Each type has an Advanced button that shows optional settings. Leave them empty to use the defaults, which work for most servers.
• Fresh values. Timestamps and nonces (one-time values) are generated for every request unless you set them.
• Signed last. Signatures cover the final method, URL, headers and body, after variables are filled in.

Auth type	Typical use
OAuth 1.0	Older APIs that sign each request with a consumer key
Digest Auth	Username and password without sending the password
NTLM	Windows authentication on IIS and SharePoint
AWS Signature	AWS services and API Gateway
Hawk	APIs that sign with a shared Hawk key
Akamai EdgeGrid	Akamai APIs
JWT Bearer	APIs that accept a JSON Web Token you sign yourself

OAuth 1.0

Signs each request with your consumer key and secret, and optionally a user's token and token secret.

Field	Meaning
Add authorization data to	Request headers sends Authorization: OAuth …. Request body or URL puts the oauth_* parameters in a form body when there is one, else in the query string.
Signature method	HMAC-SHA1, HMAC-SHA256, HMAC-SHA512, RSA-SHA1, RSA-SHA256, RSA-SHA512 or PLAINTEXT
Consumer key	Identifies your app to the service
Consumer secret	The app's secret, used to sign. Shown for HMAC and PLAINTEXT.
Access token	The user's access token. Leave it empty for 2-legged OAuth.
Token secret	The secret that came with the access token. Shown for HMAC and PLAINTEXT.
Private key	An unencrypted RSA private key in PEM form (PKCS#1 or PKCS#8). Shown for the RSA methods.

PLAINTEXT sends the secrets themselves. Use it only over https://.

Advanced

Field	Meaning
Callback URL	oauth_callback, for the request-token step
Verifier	oauth_verifier, for the access-token step
Timestamp	Seconds since 1970. Empty uses the current time.
Nonce	A unique value per request. Empty generates one.
Version	oauth_version. The default is 1.0. Empty leaves it out.
Realm	Optional realm for the Authorization header. It is not signed.
Include body hash	Adds oauth_body_hash for bodies that are not forms, so the signature covers JSON and other bodies
Add empty parameters to signature	Sends and signs empty oauth_token, oauth_callback and oauth_verifier too

Digest Auth

A username and password, proved with a hash instead of sending the password.

When you send, the first request goes out without credentials. The server answers 401 with a challenge, and ApiWorkbench answers the challenge automatically with a second request. You see the final response. The Console shows both requests.

Field	Meaning
Username	Your username for this server
Password	Never sent. Only a hash of it goes over the wire.
Don't answer the challenge	Keeps the server's 401 instead of retrying with credentials. Turn it on to look at the challenge itself.

Advanced

These are usually filled in from the server's challenge. With a Realm and Nonce set here, the first request is signed already.

Field	Meaning
Realm	From the server's WWW-Authenticate challenge
Nonce	The server nonce from the challenge
Algorithm	MD5, MD5-sess, SHA-256 or SHA-256-sess. A challenge from the server decides when it names one.
qop	Quality of protection: None, auth (protects the method and URI) or auth-int (also covers the body)
Nonce count	nc, in hex. Empty uses 00000001.
Client nonce	cnonce. Empty generates one per request.
Opaque	Echoed back to the server as it sent it

NTLM

Windows NTLMv2 authentication, for IIS and SharePoint servers. It is a three-step handshake on one connection, and ApiWorkbench does it automatically when you send.

Field	Meaning
Username	Your Windows user name. DOMAIN\user works too.
Password	Used for the NTLMv2 response. Never sent itself.

Advanced

Field	Meaning
Domain	The Windows domain. Often required by IIS servers.
Workstation	This computer's name, as the server should see it
Don't finish the handshake	Keeps the server's 401 challenge instead of answering it. Turn it on only to inspect the challenge.

AWS Signature

Signs the request with AWS Signature Version 4, covering the method, URL, headers and the exact body. Use it for AWS services and API Gateway endpoints that use IAM authorization.

Field	Meaning
Add authorization data to	Request headers signs in the Authorization header. Request URL makes a presigned URL instead, valid for 24 hours.
Access key	Your AWS access key ID
Secret key	The secret access key that goes with it

Advanced

Region and service are read from *.amazonaws.com hosts when left empty. Set them for custom domains.

Field	Meaning
AWS region	For example eu-west-1. Empty: taken from the host, else us-east-1.
Service name	The signing name of the service, for example execute-api. Empty: taken from the host.
Session token	For temporary credentials (STS, SSO). Sent as X-Amz-Security-Token.

Hawk

Signs each request with a Hawk MAC made from your key, the time and a nonce.

Field	Meaning
Hawk Auth ID	The key identifier the server gave you
Hawk Auth Key	The shared key that signs requests
Algorithm	SHA256 or SHA1. It must match the server's credentials.

Advanced

Field	Meaning
User	A user name kept with the credentials. It is not sent.
Nonce	Empty generates one per request
ext	Application data sent and signed with the request
app	Oz application ID
dlg	Oz delegated-by application ID
Timestamp	Seconds since 1970. Empty uses the current time.
Include payload hash	Signs the body and content type as well, by adding hash="…"

Akamai EdgeGrid

Signs requests to Akamai APIs with the credentials from your .edgerc file.

Field	Meaning
Access token	access_token from your .edgerc section
Client token	client_token from your .edgerc section
Client secret	client_secret from your .edgerc section

Put the host value from .edgerc in the request URL, for example in a {{baseUrl}} variable. The host of the request URL is what gets signed.

Advanced

Field	Meaning
Nonce	Empty generates a UUID per request
Timestamp	Empty uses the current time
Base URL	The host from your .edgerc, kept for reference and Postman exports
Headers to sign	Comma-separated header names included in the signature

JWT Bearer

Builds and signs a JSON Web Token on every send, from a payload you write, and sends it as a bearer token. Use it when an API accepts a token your app signs itself.

Field	Meaning
Add JWT token to	Request header or Query param
Algorithm	See the table below
Secret	The shared HMAC secret. Shown for the HS algorithms.
Secret Base64 encoded	Decodes the secret from base64 before signing. Turn it on when the provider gives the secret as base64.
Private key	An unencrypted PEM key. Shown for the RS, PS and ES algorithms.
Payload	The claims, as a JSON object

Algorithm	Signs with
HS256, HS384, HS512	HMAC with a shared secret
RS256, RS384, RS512	RSA PKCS#1 v1.5 with a private key (PKCS#1 or PKCS#8)
PS256, PS384, PS512	RSA-PSS with a private key
ES256, ES384, ES512	ECDSA with a P-256, P-384 or P-521 key (SEC1 or PKCS#8)

Variables are filled in before signing, so the payload can hold fresh values:

{
  "sub": "1234567890",
  "iat": {{$timestamp}}
}

{{$timestamp}} is the current time in seconds. See Dynamic variables.

Advanced

Field	Meaning
Request header prefix	Written before the token in the header. The default is Bearer. Empty sends the token alone. Shown when the token goes in the header.
Query param name	The query parameter that carries the token. The default is token. Shown when the token goes in the URL.
JWT headers	Extra header fields as JSON, such as {"kid": "key-1"}. alg and typ are set for you.

Private keys

OAuth 1.0 (RSA methods) and JWT Bearer take a private key as PEM text. Paste the whole key, including the -----BEGIN and -----END lines. The key must not be encrypted with a passphrase.

DANGER

A private key pasted here is stored as plain text with the request and is included in workspace exports. Use a test key where you can, and never share an export that contains a production key.

Next steps

• Authorization
• OAuth 2.0
• Console
• Proxy and certificates