Authentication

Authentication

ApiArk supports 8 authentication methods with inheritance from collection → folder → request.

---

Auth Inheritance

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.

In YAML

# 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

---

None

No authentication. Useful for public endpoints.

auth:
  type: none

---

Bearer Token

Sends Authorization: Bearer <token> header.

auth:
  type: bearer
  token: "{{accessToken}}"

Tip: Use environment secrets for tokens so they're never committed to Git.

---

Basic Auth

Sends Authorization: Basic <base64(username:password)> header.

auth:
  type: basic
  username: "{{apiUser}}"
  password: "{{apiPassword}}"

---

API Key

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

---

OAuth 2.0

Full OAuth 2.0 implementation with all major grant types.

Authorization Code (most common)

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:

1. Click "Get Token" in the auth panel
2. Browser opens the authorization URL
3. You log in and authorize
4. ApiArk intercepts the callback via apiark://oauth/callback
5. Token is exchanged and stored

Authorization Code + PKCE

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

Client Credentials

Machine-to-machine authentication.

auth:
  type: oauth2
  grantType: client_credentials
  tokenUrl: https://auth.example.com/token
  clientId: "{{clientId}}"
  clientSecret: "{{clientSecret}}"
  scope: "api:read"

Password Grant

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}}"

Implicit Grant

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

Token Management

• 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

---

Digest Auth

Challenge-response authentication per RFC 7616.

auth:
  type: digest
  username: "{{digestUser}}"
  password: "{{digestPassword}}"

ApiArk handles the challenge/response flow automatically:

1. First request gets a 401 with WWW-Authenticate: Digest header
2. ApiArk computes the digest response
3. Retries the request with the correct Authorization header

---

AWS Signature v4

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.

---

NTLM

Windows-based authentication for corporate/legacy systems.

auth:
  type: ntlm
  username: "{{ntlmUser}}"
  password: "{{ntlmPassword}}"
  domain: CORPORATE     # optional
  workstation: DESKTOP   # optional

---

JWT Bearer

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.

---

Security Best Practices

1. Always use secrets for tokens, passwords, and keys — never plain text in YAML
2. Use environment variables so credentials differ between dev/staging/prod
3. Prefer OAuth 2.0 + PKCE over password-based auth
4. Rotate tokens regularly — use the refresh flow
5. Check your .gitignore — .env should always be excluded
6. Auth tokens in history are stored as [REDACTED]