Yaak API Client

The HTTP Snippet Plugin provides several advanced capabilities for generating accurate code:

• Template Variable Rendering: It renders template variables before generating snippets, ensuring the output reflects real values.
• Body Type Support: Supports JSON, form-urlencoded, multipart, GraphQL, and raw text bodies.
• Authentication Inclusion: Automatically includes authentication headers such as Basic, Bearer, and API Key.
• Parameter Inclusion: Includes query parameters and custom headers in the generated code.

The JWT plugin manages the lifecycle of a JSON Web Token (RFC 7519) to facilitate secure API communication.

The Token Structure:

• Header: Specifies the token type and the signing algorithm used.
• Payload: Contains the claims (data such as user identity, permissions, or expiration timestamps).
• Signature: A cryptographic hash that ensures the token has not been tampered with.

The Request Flow: When a request is made, the plugin uses your configured algorithm, secret/key, and claims to generate a signed token. This token is then automatically injected into the Authorization header using the Bearer scheme.

Users can customize the Yaak experience through:

• Template Tags: Insert dynamic values such as UUIDs or timestamps into requests.
• Custom Themes: Choose from built-in themes or create your own.
• Plugin System: Create plugins to extend authentication logic, template tags, or the user interface.

The OAuth 2.0 plugin supports four primary grant types. Choose the one that matches your API provider's security model:

• Authorization Code Flow: The most secure and common flow for web applications. Supports optional PKCE (Proof Key for Code Exchange) and automatic token refresh.
• Client Credentials Flow: Used for server-to-server authentication where no user interaction is required.
• Implicit Flow: A legacy flow for single-page applications. It provides direct access token retrieval but does not support refresh tokens.
• Resource Owner Password Credentials Flow: Direct username/password exchange. Use this only with trusted applications. Supports automatic token refresh.

Yaak allows for structured API management through the following features:

• Workspaces: Group requests into workspaces and nested folders.
• Environments: Use environment variables to switch between different stages like dev, staging, and prod.
• Filesystem Mirroring: Mirror workspaces to your local filesystem, enabling version control via Git or synchronization with services like Dropbox.

Yaak supports multiple communication protocols and data inspection methods:

Supported Protocols:

• REST
• GraphQL
• gRPC
• WebSocket
• Server-Sent Events (SSE)

Key Capabilities:

• Importing: Import existing collections from Postman, Insomnia, OpenAPI, Swagger, or Curl.
• Inspection: Filter and inspect API responses using JSONPath or XPath.

Yaak provides several mechanisms to handle sensitive data and authentication:

• Authentication Methods: Supports OAuth 2.0, JWT, Basic Auth, and custom plugins.
• Secret Management: Secure sensitive values using encrypted secrets.
• OS Integration: Stores secrets directly in your operating system's keychain.

JSONPath uses a dot-notation syntax to navigate and query JSON structures. Use these operators to build your expressions:

• $ : The root element.
• . : Child element navigation.
• .. : Recursive descent (searches through all levels of the hierarchy).
• * : Wildcard (matches any element).
• [] : Array indexing, slicing, or filtering.
• ?() : Filter expression (used within brackets to apply logic).

When using the CLI, especially within automated scripts or agentic workflows, note the following syntax rules:

• Template Variables: Use ${[ my_var ]} syntax. Note that {{ ... }} is not supported.
• Template Functions: Use ${[ namespace.my_func(a='aaa',b='bbb') ]}.
• Schema Inspection: Before creating or updating data, inspect the model's JSON Schema using yaak request schema <model> (e.g., yaak request schema http).
• Non-interactive Deletion: Deletion commands require confirmation. Use the --yes flag to bypass confirmation in non-interactive environments.

SigV4 signs requests by creating a hash of key request components—including the HTTP method, URL, headers, and optionally the payload—using your AWS credentials. The resulting HMAC signature is then injected into the Authorization header along with credential scope metadata.

Every request signed via this method must include a timestamp in the X-Amz-Date header. If using temporary credentials, a session token must also be included.

Authorization: AWS4-HMAC-SHA256 Credential=AKIA…/20251011/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=abcdef123456…