Understanding the API Integration Framework

This guide explains how Yurbi's API integration framework works, what every field and parameter type is for, and a recommended workflow for setting up an integration with any REST API. It's written for someone who's comfortable reading API documentation but new to Yurbi's specific way of modeling integrations.

If you're looking for a step-by-step walkthrough of a specific integration (Microsoft Excel, Google Sheets), see the Related Articles at the bottom. This document is the underlying reference those guides assume.

What This Framework Does

The API integration framework lets you pull data from any REST API and surface it inside Yurbi as a regular table. Once configured:

• Yurbi fetches data from the vendor's API on demand or on a schedule

• The fetched data lands in Yurbi tables you can join, query, and report on like any other data source

• Authentication, token renewal, and pagination are handled automatically once you've configured them

Common uses include pulling customer/ticket data from a SaaS tool (CRM, help desk), reading spreadsheets from cloud storage (Google Sheets, Excel on SharePoint), syncing data from accounting tools, or mirroring data from any internal or third-party API your team relies on.

The result is that data living outside your databases — in SaaS tools your team uses — becomes reportable in the same workflow as your operational data.

Before You Open Yurbi: Test in Postman First

The single most useful thing you can do before configuring an API integration in Yurbi is to make the API call succeed in a dedicated API client first — Postman, NativeRest, Insomnia, or any equivalent. Don't try to debug Yurbi configuration and vendor API quirks at the same time.

The reasoning is practical. Every vendor's REST API has its own conventions, and the docs are often slightly out of sync with the actual behavior:

• The auth header might want a literal prefix you didn't notice (Bearer vs Token )

• A query parameter might be case-sensitive (?Status=open vs ?status=open)

• The response might be wrapped in a JSON envelope the docs don't show

• Pagination might behave differently than documented when you reach the last page

Until you can reliably make the call return data outside Yurbi, you don't know what the request actually needs to look like — and you'll waste time blaming Yurbi for the vendor's quirks.

What to capture from your Postman test

For each API endpoint you want to bring into Yurbi, write down:

1. The full URL including query string parameters

2. HTTP method (almost always GET for reading data)

3. Auth method — exactly what header(s) you sent and what they contained

4. Other headers the vendor required (Accept, version headers, tenant IDs)

5. The full response JSON — specifically, where in the JSON the actual data array lives

6. Pagination behavior — what query params control it, what tells you there are more pages, and how many records come back per page

7. Anything else weird — rate limit headers, undocumented fields, etc.

With those notes in hand, configuring Yurbi becomes a translation exercise rather than a debugging exercise.

The Four Connection Types

When you create a new API integration via Settings → Integrations → Create App → APIs, the first decision is the Api Connection type. Pick based on how the vendor's API authenticates.

How vendor docs map to your choice

Read the vendor's authentication section. What you see there → which connection type to pick:

• "Pass ?api_key=YOUR_KEY in the URL" → Manual (bake the key into the endpoint URL), or HttpBasicAuthenticator if you'd rather send it as a header

• "Send Authorization: Basic <base64(username:password)>" → HttpBasicAuthenticator

• "Send Authorization: Bearer <static-token>" or "X-API-Key: <key>" → Manual or HttpBasicAuthenticator

• "POST your client_id and client_secret with grant_type=client_credentials to get an access token" → Client Credentials

• "Redirect the user to /authorize, then exchange the code for a token" → oAuth 2.0

• Anything stranger (custom signed requests, HMAC, multi-step handshakes that aren't standard OAuth) → Manual

Telling Client Credentials from oAuth 2.0

These are the two most commonly confused. The distinguishing question is simple: does a human have to log in?

• If the vendor's flow sends a user to a consent screen in a browser, that's oAuth 2.0. You'll get back both an access token and a refresh token.

• If your application authenticates as itself — client ID and secret, no browser, no consent — that's Client Credentials. There is no refresh token; when the access token expires, Yurbi simply requests a new one.

Client Credentials is the better choice whenever the vendor supports it, because there's no user session to expire and nothing to re-authorize months later.

Anatomy of an API Integration

Every API integration in Yurbi has the same structure, regardless of connection type:

1. The API Connection itself — the wrapper. Has a name, description, connection type, and active status.

2. Authentication sections — which ones appear depends on the connection type you picked. These configure the URLs and credentials Yurbi uses to obtain a token.

3. Endpoints — one per API URL you want to call. Each endpoint becomes one (or more) tables in Yurbi.

4. Endpoint Parameters — per-endpoint settings that control how Yurbi builds each request: auth headers, custom headers, pagination, dynamic value substitution.

5. Reusable Dynamic Parameters (optional, at the connection level) — named parameter sources that let one endpoint reference data from another endpoint or from a saved Yurbi report.

The two-step form

When you create a new API, you'll first enter just the name, description, connection type, and active status, then click Continue. Yurbi saves the connection and then reveals the sections relevant to the connection type you chose.

This is deliberate: endpoints and authentication settings attach to a saved API record, so there's nothing meaningful to configure until the record exists. When you reopen an existing API to edit it, everything is visible immediately.

Endpoints — One Per Resource You Want as a Table

Click Add Endpoint under the Api Endpoints section. You'll see:

Below the URL, you add parameters that customize how the request is built — auth headers, pagination, custom headers, and so on. The parameter system is covered in detail below.

Table naming

Fetched data lands in a table named:

api_{apiId}_{endpointId}_{EndpointName}_{ResponseBy}

So an endpoint named albums with Response By set to items, on API 7, endpoint 3, produces api_7_3_albums_items.

This matters more than it looks. Because Response By is part of the table name, changing it after you've fetched data creates a new set of tables and leaves the old ones behind. If you need to change Response By on an endpoint that has already run, plan to clean up the old tables and repoint anything in Architect that referenced them.

If the response contains nested arrays, Yurbi may create additional related tables alongside the main one.

Response By — Where the Data Lives in the JSON

This single field is responsible for more "endpoint fetched but the table is empty" frustration than any other. The fix is almost always understanding the response shape.

REST APIs return JSON in one of three common shapes. Look at the response you captured in Postman to identify which one applies.

Shape A — Data at the root level (a bare array):

[
  {"id": 1, "name": "Alpha"},
  {"id": 2, "name": "Beta"}
]

→ Set Response By to blank (leave the field empty).

Shape B — Data wrapped under a key:

{
  "data": [
    {"id": 1, "name": "Alpha"},
    {"id": 2, "name": "Beta"}
  ],
  "meta": {"total": 2, "page": 1}
}

→ Set Response By to data.

Shape C — Vendor-specific key name:

{
  "items": [
    {"id": 1001, "name": "..."},
    {"id": 1002, "name": "..."}
  ],
  "total": 951,
  "next": "https://api.vendor.com/albums?offset=20"
}

→ Set Response By to items.

How to figure out the right value

Open your Postman test, look at the response body. The JSON key whose value is the array of records is your Response By value. If the array is at the top level (no key wrapping it), leave the field blank.

Watch for near-misses. In Shape C above, an integration configured with albums instead of items — because the endpoint is about albums — will not find the records array. Match the exact key from the response body, not the name of the resource.

Single-object responses (a detail endpoint that returns one record, not an array) often work with Response By blank — Yurbi treats the entire object as a one-row response. But if the single object is wrapped (e.g., {"ticket": {...}}), set Response By to that wrapper key.

The Parameter Type Catalog

Every parameter row on an endpoint has a Param Type dropdown that tells Yurbi how to use that parameter when building the request. Here's every option, what it means, and when you'd use it.

Is Auth Header

Puts the parameter into the HTTP Authorization (or other auth) header. The behavior depends on the Authentication column setting (covered later).

Pattern 1 — Managed token (used with Client Credentials or oAuth 2.0, after authentication completes):

• Name: Authorization

• Param Type: Is Auth Header

• Value: access_token

• Authentication: Authentication

Note that the value is the literal text access_token — it is a lookup key, not the token itself. Yurbi substitutes the currently stored token and adds the Bearer prefix automatically. You never paste a managed token into this field.

Pattern 2 — HTTP Basic Auth (vendor wants username/password):

• Name: your username (e.g., david@yourcompany.com)

• Param Type: Is Auth Header

• Value: your password or API key

• Authentication: HttpBasicAuthenticator (Yurbi base64-encodes and sends as Authorization: Basic <encoded>)

Pattern 3 — Custom or static auth header (vendor wants X-API-Key, or a personal access token you paste in yourself):

• Name: X-API-Key (or Authorization)

• Param Type: Is Auth Header

• Value: your key, or the full literal header value such as Bearer pat...

• Authentication: Authentication

Is Header

A non-auth HTTP header. Examples:

• Accept header: Name = Accept, Value = application/json

• Tenant or workspace ID: Name = X-Tenant-Id, Value = your-tenant-id

• API version pin: Name = Api-Version, Value = 2024-01-01

The vendor's docs will tell you when these are required. Some APIs require a second, non-auth header on every call in addition to the token — this is where that goes.

Is Page

Pagination — for APIs that use page numbers, like ?page=1, ?page=2, ....

• Name: the query parameter name the API expects (commonly page)

• Param Type: Is Page

Is Page needs More Check to continue past the first page. On its own it sends the page parameter but has no way to know whether more data exists. See the Pagination section below for the full combination.

More Check

Tells Yurbi how to detect when there are more pages to fetch, by naming a field in the API's response.

• Name: the response field name that signals more results

Two forms are supported:

• A total count — e.g. {"total_count": 487}. Yurbi compares the total against how many records it has already retrieved and continues until it has them all. This form requires a Records Per Page parameter as well, since the calculation needs to know the page size.

• A boolean — e.g. {"has_more": true}. Yurbi continues while the value is true and stops when it turns false.

Is Offset

Pagination — for APIs that return a token or cursor telling you where to resume, which you pass back on the next call (common in Airtable, and in many APIs that call it a "cursor" or "continuation token").

• Name: the query parameter name (commonly offset)

• Param Type: Is Offset

Yurbi reads the offset value out of each response and sends it on the next request, stopping automatically when the API stops returning one. No More Check is needed.

Is Offset (Numeric)

Pagination — for APIs that use a numeric record offset, e.g. ?offset=0, ?offset=50, ?offset=100.

• Name: the query parameter name (commonly offset, skip, or start)

• Param Type: Is Offset (Numeric)

• Value: leave blank — Yurbi calculates it

Pair this with Records Per Page. The offset advances by the page size on each call, so Yurbi needs to know what that page size is. See the Pagination section below.

Choosing between Is Offset and Is Offset (Numeric) comes down to what the vendor sends back: if the response hands you an opaque value to pass to the next call, use Is Offset; if you're expected to count records yourself, use Is Offset (Numeric).

Records Per Page

Tells the API how many records to return per call (e.g., ?limit=50, ?per_page=100, ?pageSize=200), and tells Yurbi what page size to expect.

• Name: the query parameter name (commonly limit, per_page, pageSize, count)

• Param Type: Records Per Page

• Value: the page size (e.g. 100)

Most vendor APIs cap this at 100 or 200 — check the docs and don't exceed the cap, or the API may reject the request outright.

Set this value to the number of records the API actually returns per call. If you request 100 but the vendor caps responses at 50, pagination will end early. Confirm the real page size in Postman.

Json Body

For endpoints that require a POST with a JSON request body rather than query string parameters. Each Json Body parameter becomes a field in the body Yurbi sends.

• Name: the JSON field name

• Param Type: Json Body

• Value: the value to send

Used with Method = POST on APIs where reads are expressed as searches or filters.

From Dynamic Param

References a reusable dynamic parameter you've defined separately at the API connection level. Used for parent → child fetch patterns where the value of one column from a previous endpoint's results is substituted into this endpoint's URL.

• Name: a label matching the URL placeholder (e.g., customer_id)

• Param Type: From Dynamic Param

• Value: dropdown — select from your saved dynamic parameters

The URL contains a placeholder like https://api.vendor.com/customers/{customer_id}/invoices. At fetch time, Yurbi runs the endpoint once per row from the dynamic param's source, substituting each value into the URL.

See the Reusable Dynamic Parameters section below for the full setup.

Pagination — Putting the Pieces Together

Pagination is the most common source of "it worked but I'm missing data." Work out which style the vendor uses, then use the matching combination.

Three rules worth committing to memory:

1. Is Page alone fetches one page. It needs More Check to know whether to continue. This is the most common cause of a page-based integration quietly returning only the first 50 or 100 records.

2. Both numeric styles need Records Per Page. Without it, Yurbi has to infer the page size from the first response, which works but is less reliable than telling it outright.

3. Token-based Is Offset is self-terminating. It stops when the vendor stops returning an offset, so it needs neither More Check nor a page size to end correctly — though Records Per Page is still worth setting to control how many records come back per call.

Verifying a paginated fetch

After the first run of a paginated endpoint, compare the row count in the resulting table against the total the vendor reports. If the numbers don't match, the usual causes are:

• A page-based setup missing More Check

• A Records Per Page value that doesn't match what the API actually returns

• A Response By value that doesn't match the response body

The Authentication Column

Each parameter row also has an Authentication dropdown with two values:

For the vast majority of parameter rows, Authentication is the right choice. Switch to HttpBasicAuthenticator only when you're configuring an HTTP Basic Auth credential.

The "Is Query Param" Checkbox

Separate from Param Type, every parameter row has an Is Query Param checkbox. It controls whether the parameter is appended to the URL as a query string parameter (?name=value) or used elsewhere (in a header, in a placeholder substitution, etc.).

For most cases the behavior is implicit in the Param Type:

• Is Auth Header and Is Header — value goes in the header, checkbox doesn't apply

• Is Page, Is Offset, Is Offset (Numeric), Records Per Page — value goes in the query string regardless of the checkbox

• Json Body — value goes in the request body

• From Dynamic Param — value substitutes into a URL placeholder

You'll mostly leave this unchecked unless you're explicitly adding a static query string parameter — and those are usually simpler to bake into the endpoint URL itself.

Credentials and What Yurbi Shows

Credentials you enter — client secrets, refresh tokens, API keys, passwords — are stored encrypted and are not displayed back to you once saved. When you reopen an authentication form, sensitive values appear as __SECRET_UNCHANGED__ in a locked field rather than as the value itself.

To change one, click the locked field. It clears and unlocks, and you can type the new value. Saving a form without touching a locked field leaves the stored credential exactly as it was.

A value is treated as sensitive when it's part of a token exchange, or when its name contains any of: secret, password, passwd, token, key, apikey, authorization, bearer, credential (case-insensitive).

Two practical consequences:

• You can't retrieve a credential from Yurbi after entering it. If you need the value again, get it from the vendor's dashboard or your own password manager. Keep your own record when you generate a key.

• Endpoint-level parameters follow the same naming rule. A parameter named Authorization or X-API-Key is masked; one named something unrelated is not. Name credential parameters descriptively so they're recognized.

If a credential is wrong, you don't need to see it to diagnose the problem — use Test Connection, which reports the provider's own error message (see Running and Monitoring below).

Reusable Dynamic Parameters

Dynamic parameters enable two important patterns:

• Parent → child fetching: a list endpoint returns IDs; a detail endpoint runs once per ID

• Yurbi-data-driven fetching: a Yurbi report (e.g., "active customer IDs from our CRM database") drives which records to fetch from a separate API

This is a two-step configuration: first you define the named parameter at the connection level, then any endpoint can reference it.

Step 1: Define the dynamic parameter

In the API connection form, under Api Endpoints Parameters, click Add Parameters. The form asks for:

Select Parameter Type — pick one of:

• From Table — source the values from a column in another endpoint's resulting table (in this same API connection):

  • Select Table — pick the endpoint's data table

  • Select Column — pick the column to iterate

  • Enter Parameter Value — the name of this dynamic param (e.g., customer_id)

• From Document — source the values from a saved Yurbi report (a database query result):

  • Select Document — pick the saved report

  • Enter Parameter Value — the name of this dynamic param

The "Enter Parameter Value" name is what shows up in the dropdown when other endpoints reference it.

Step 2: Reference it from an endpoint

In an endpoint's URL, use a placeholder syntax matching the parameter name:

https://api.vendor.com/customers/{customer_id}/invoices

Add a parameter row on the endpoint:

• Name: customer_id (must match the placeholder in the URL)

• Param Type: From Dynamic Param

• Value: pick customer_id from the dropdown (your saved dynamic param)

How the iteration works

When this endpoint is fetched:

1. Yurbi looks at the source (the table or document the dynamic param points to)

2. For each row in that source, Yurbi makes one API call, substituting the column value into the URL placeholder

3. All results are appended into a single table for this endpoint

4. An additional column called id_yurbi is added automatically — it contains the source row's identifier, letting you join parent and child tables in Architect

One call per source row. If your parent endpoint returns 500 conversations, the child endpoint will make 500 API calls — sequentially. For large parent sets, plan your schedule cadence around the vendor's rate limits.

Joining parent and child in Architect

After both endpoints have fetched, you'll have two tables — for example api_4_9_Conversations_items (the parent list, with a conversation_id column) and api_4_11_ConversationDetail_ (the per-conversation details, with an id_yurbi column).

In Architect, bring both tables into your app and join parent.conversation_id = child.id_yurbi. You'll then have detail data accessible per parent record for reporting.

Client Credentials — Setup

Pick this connection type when the vendor authenticates your application directly, with no user login step.

After clicking Continue on the connection details, open Add Details under API Authorization List. Configure:

Some vendors require additional parameters here, such as scope or audience. Add them as further parameter rows with the names the vendor specifies.

Then click Authenticate once to acquire the first token. On each endpoint, add an auth header parameter:

• Name: Authorization

• Param Type: Is Auth Header

• Value: access_token

Yurbi stores the token, sends it with the Bearer prefix on every request, and acquires a new one automatically when it expires. There is no refresh token in this flow and nothing to renew manually.

Migrating an existing integration to Client Credentials

If you're currently pasting a token into an endpoint parameter by hand and re-pasting it when it expires, and the vendor supports the client credentials grant, converting takes a few minutes per API and doesn't disturb your existing tables:

1. Change the connection type to Client Credentials

2. Configure the token URL, method, client_id, client_secret, and grant_type as above

3. Clear any leftover refresh token parameters from the previous configuration

4. Change the endpoint's Authorization parameter from the static pasted token to Is Auth Header with the value access_token

5. Click Authenticate once to seed the token

Table names don't change, so reports built on this data continue to work.

oAuth 2.0 (and Manual) — The Three URL Forms

If you picked oAuth 2.0 — or Manual for a non-standard multi-step flow — the form shows three URL sections above the endpoints, corresponding to the steps of the authorization code flow:

After configuring all three forms, click Authenticate in the API Authorization List section. A popup walks the user through the vendor's login, Yurbi receives the tokens, and stores them. Endpoints can then use the stored access_token via an Is Auth Header parameter.

Once authenticated, renewal is automatic — when an access token expires, Yurbi uses the stored refresh token to obtain a new one.

For complete OAuth setup walkthroughs, see the Microsoft Excel OAuth2 and Google Sheets OAuth2 guides linked at the bottom.

A note on the OAuth callback URL

Yurbi serves the OAuth callback at /apiconnection.html on whatever domain your Yurbi instance is reachable at. For self-hosted Yurbi deployments — which is most of them — the callback URL looks like https://yurbi.yourcompany.com/apiconnection.html.

Critically, the callback URL must be reachable from the user's browser when they click Authenticate. For a Yurbi instance behind a firewall, this typically means exposing at minimum the /apiconnection.html endpoint publicly via your reverse proxy, with a valid TLS certificate. The vendor doesn't directly call this URL — the user's browser is redirected to it after sign-in completes — but it needs to be resolvable wherever that browser is running.

Running and Monitoring

Test Connection

For oAuth 2.0 and Manual integrations, a Test Connection button sits beside Authenticate. It exercises only the token renewal step — no user login, no data fetch — and reports the provider's own error message if it fails.

Use it to confirm an integration will keep working before you rely on a schedule, or to diagnose a failing fetch. Because it uses the stored refresh token, the vendor may issue a replacement; that's normal and Yurbi stores the new one.

For Client Credentials integrations, the Authenticate button does the same job — it requests a fresh token and reports any error from the provider — so no separate test button is shown.

Connect — fetching data

Choose Connect from an endpoint's Actions menu to fetch data on demand.

The fetch runs on the server. Once it has started you can close the panel or navigate elsewhere — the fetch continues, and the result is recorded when it finishes. Purge & Connect does the same but empties the endpoint's tables first, which is what you want after changing an endpoint's structure or when you suspect stale rows.

The Status column

The Api Endpoints list has a Status column showing the outcome of each endpoint's most recent run:

Status persists across page refreshes and covers both manual and scheduled runs, so you can check on a schedule's health without watching it happen.

Reading a failure

When Status shows Failed or Interrupted, click it. A window opens with the reason for the failure and a detailed trace of the run, which you can copy for a support ticket.

Most failures fall into a few categories:

• 401 / invalid token — credentials are wrong or expired. Use Test Connection, or re-authenticate.

• 429 / rate limited — you've exceeded the vendor's quota. Yurbi retries automatically and honors the vendor's Retry-After header, but will give up if the limit persists. Reduce your schedule frequency.

• A vendor error message — the provider's own text, usually pointing at a malformed request or a permission problem.

Scheduling

Choose Schedule from an endpoint's Actions menu to set up an automatic refresh. You can schedule by minutes, or daily, weekly, monthly, quarterly, or yearly with a start date and time.

Choosing Schedule again on an endpoint that already has one opens the existing schedule for editing. Delete Schedule removes it; the endpoint and its data are unaffected.

A few things worth knowing:

• If a scheduled run starts late, the next run is calculated from the current time rather than backfilling missed intervals.

• Set the frequency against the vendor's rate limit, especially when using dynamic parameters — a parent with 1,000 children refreshed every 15 minutes is 4,000+ calls an hour.

• A manual Connect and a scheduled run of the same endpoint at the same moment can interfere with each other. If you're testing manually, it's worth pausing a frequent schedule first.

Deconstructing Vendor API Documentation — A Checklist

When you sit down with a new vendor's API docs, work through these sections in order. The answer to each maps to specific Yurbi configuration.

1. Authentication

Usually a top-level section called "Authentication," "Auth," "Getting Started," or "API Keys."

• Which scheme? API key (in URL or header), HTTP Basic Auth, OAuth 2.0 authorization code, OAuth 2.0 client credentials, custom?

• How is it provisioned? Self-service in their dashboard? Admin only? Per-user or per-application?

• How is it sent? Header name? URL parameter name?

• Does it expire? If so, how is it renewed?

Map your answer to a connection type using the table earlier in this guide.

2. Base URL and Resource Paths

What's the API root (e.g., https://api.vendor.com/v3)? What endpoints do you need? Most APIs follow a /resource and /resource/{id} pattern.

Pick the endpoints you actually need. One endpoint per data table you want in Yurbi. Don't add every endpoint the vendor offers; just the ones whose data you need to report on.

3. Response Format

Pull up a sample response in Postman.

• Where is the data array? Top-level array → Response By blank. Nested under a key → Response By = that key, exactly as spelled.

• What does each record look like? Just for awareness — Yurbi auto-detects columns from the JSON.

4. Pagination

Figure out which style the vendor uses, and — just as important — how many records come back per call. Use the pagination table earlier in this guide to pick the parameter combination.

Also note the stopping signal: a total_count, a has_more boolean, or an offset the API stops returning.

5. Required Headers

Many APIs require headers beyond auth: Accept: application/json, version pins, tenant identifiers. Each goes in as an Is Header parameter.

6. Rate Limits

Note the vendor's rate limit — per minute, per hour, or per day. This determines your schedule cadence, and matters most when using dynamic parameters.

7. Anything Else Unusual

• Eventual consistency (data created via API isn't immediately readable)

• Soft-deleted records that appear in some endpoints but not others

• Different field naming conventions between endpoints

Postman-test these as you go.

Worked Example 1 — Static API Key

A support platform, "AcmeTickets," that authenticates with a static key.

Authentication: Send X-Api-Key: <your-key> header on every request. Base URL: https://api.acmetickets.com/v3 List tickets: GET /tickets, returns {"data": [...], "meta": {"total_count": 487, "page": 1, "per_page": 50}} Pagination: ?page=N&per_page=M (max 100). Ticket details: GET /tickets/{ticket_id} — a single ticket object. Rate limit: 120 requests/minute.

Configuration

Build order

1. Register the connection — name, description, type Manual — and click Continue

2. Add Endpoint 1 with the URL, Response By, and the pagination + auth parameters

3. Connect Endpoint 1 and confirm the row count matches the vendor's total_count

4. Add the dynamic parameter ticket_id sourced from Endpoint 1's table

5. Add Endpoint 2 with the placeholder URL, dynamic param, and auth header

6. Connect Endpoint 2 and verify the detail rows fetch

7. In Architect, join endpoint1.id = endpoint2.id_yurbi

8. Schedule both endpoints

Worked Example 2 — Client Credentials with Numeric Offset

A music catalog API that issues short-lived tokens from a client ID and secret, and paginates by numeric offset.

Token endpoint: POST https://accounts.example.com/api/token with client_id, client_secret, grant_type=client_credentials Albums: GET https://api.example.com/v1/artists/{id}/albums, returns {"items": [...], "total": 951, "next": "..."} Pagination: ?offset=N, 5 records per page for this endpoint.

Configuration

Connection: type Client Credentials.

API Authorization List:

Endpoint albums, method GET, URL https://api.example.com/v1/artists/.../albums, Response By = items.

Two details worth highlighting, because both are easy to get wrong:

• Response By is items, not albums. The endpoint is about albums, but the JSON key holding the records is items. Using the resource name instead of the response key is a common mistake.

• Don't add a parameter the API doesn't accept. This vendor rejects an explicit limit parameter on this endpoint even though it paginates by offset. Set the page size in Records Per Page and let Yurbi handle the rest. Your Postman test will tell you which parameters the endpoint tolerates.

The resulting table is api_7_3_albums_items.

Common Mistakes and Gotchas

Picking a Connection Type in Practice

Most integrations land in one of three places:

• A static key or token that never expires → Manual, or HttpBasicAuthenticator if the vendor wants HTTP Basic credentials. Simple, and nothing to renew.

• Machine-to-machine OAuth with a client ID and secret → Client Credentials. Prefer this whenever the vendor offers it: tokens renew automatically and there's no user session to expire.

• A flow requiring a user to sign in and consent → oAuth 2.0.

Manual also serves as the fallback for anything unusual — custom handshakes, non-standard grant types, vendor-specific session tokens — where the OAuth labeling would be misleading.

Related Articles

• Microsoft Excel (OneDrive for Business / SharePoint via OAuth2) — a complete OAuth 2.0 walkthrough

• Google Sheets (OAuth2) — another OAuth 2.0 example

• Google Sheets (Public API) — the simplest integration style, no auth flow

• Microsoft Excel (Personal OneDrive) — when API-based access isn't an option

For unresolved issues setting up a specific integration, contact your Yurbi administrator or support contact.