-
Notifications
You must be signed in to change notification settings - Fork 57
Authentication
ApiArk supports 8 authentication methods with inheritance from collection → folder → request.
Collection auth (default)
└── Folder auth (overrides collection)
└── Request auth (overrides folder)
Set auth at the collection level and all requests inherit it. Override at the folder or request level when needed.
# Request-level auth override auth: type: bearer token: "{{accessToken}}"
# Inherit from parent (default behavior) auth: type: inherit
# No auth for this specific request auth: type: none
No authentication. Useful for public endpoints.
auth: type: none
Sends Authorization: Bearer <token> header.
auth: type: bearer token: "{{accessToken}}"
Tip: Use environment secrets for tokens so they're never committed to Git.
Sends Authorization: Basic <base64(username:password)> header.
auth: type: basic username: "{{apiUser}}" password: "{{apiPassword}}"
Sends the API key as a header or query parameter.
# As header (default) auth: type: apikey key: X-API-Key value: "{{apiKey}}" in: header # As query parameter auth: type: apikey key: api_key value: "{{apiKey}}" in: query
Full OAuth 2.0 implementation with all major grant types.
auth: type: oauth2 grantType: authorization_code authUrl: https://auth.example.com/authorize tokenUrl: https://auth.example.com/token clientId: "{{oauthClientId}}" clientSecret: "{{oauthClientSecret}}" scope: "read write" redirectUrl: apiark://oauth/callback
Flow:
- Click "Get Token" in the auth panel
- Browser opens the authorization URL
- You log in and authorize
- ApiArk intercepts the callback via
apiark://oauth/callback - Token is exchanged and stored
More secure variant that doesn't require a client secret.
auth: type: oauth2 grantType: authorization_code usePkce: true authUrl: https://auth.example.com/authorize tokenUrl: https://auth.example.com/token clientId: "{{oauthClientId}}" scope: "read write" redirectUrl: apiark://oauth/callback
Machine-to-machine authentication.
auth: type: oauth2 grantType: client_credentials tokenUrl: https://auth.example.com/token clientId: "{{clientId}}" clientSecret: "{{clientSecret}}" scope: "api:read"
Direct username/password exchange (legacy, not recommended for new APIs).
auth: type: oauth2 grantType: password tokenUrl: https://auth.example.com/token clientId: "{{clientId}}" username: "{{username}}" password: "{{password}}"
Returns token directly in the redirect URL (legacy, use PKCE instead).
auth: type: oauth2 grantType: implicit authUrl: https://auth.example.com/authorize clientId: "{{clientId}}" scope: "read" redirectUrl: apiark://oauth/callback
- Tokens are stored in memory during the session
- Click "Refresh" to refresh an expired token
- Token expiry is tracked and you're warned before expiry
- Cached tokens work offline until they expire
Challenge-response authentication per RFC 7616.
auth: type: digest username: "{{digestUser}}" password: "{{digestPassword}}"
ApiArk handles the challenge/response flow automatically:
- First request gets a 401 with
WWW-Authenticate: Digestheader - ApiArk computes the digest response
- Retries the request with the correct
Authorizationheader
Signs requests for AWS services.
auth: type: aws4 accessKey: "{{awsAccessKey}}" secretKey: "{{awsSecretKey}}" region: us-east-1 service: execute-api sessionToken: "{{awsSessionToken}}" # optional, for temporary credentials
Supports all AWS services including S3, API Gateway, Lambda, DynamoDB, etc.
Windows-based authentication for corporate/legacy systems.
auth: type: ntlm username: "{{ntlmUser}}" password: "{{ntlmPassword}}" domain: CORPORATE # optional workstation: DESKTOP # optional
Generate and send JWT tokens with custom claims.
auth: type: jwt algorithm: HS256 # HS256, HS384, HS512, RS256, RS384, RS512 secret: "{{jwtSecret}}" payload: sub: "user123" aud: "api.example.com" exp: "{{$timestamp + 3600}}" iat: "{{$timestamp}}" custom_claim: "value" headerPrefix: "Bearer" # default
The JWT is generated fresh on each request with the current timestamp.
- Always use secrets for tokens, passwords, and keys — never plain text in YAML
- Use environment variables so credentials differ between dev/staging/prod
- Prefer OAuth 2.0 + PKCE over password-based auth
- Rotate tokens regularly — use the refresh flow
-
Check your
.gitignore—.envshould always be excluded - Auth tokens in history are stored as
[REDACTED]
Getting Started
Core Features
Advanced Features
Tools
Resources