Connection Profiles

Connection profiles define how Tagnet connects and authenticates to an external system, such as your ERP or WMS. You configure a profile once, and any number of workflow actions can reference it. If your integration's credentials change or the profile is renamed, every action that uses it keeps working.

Overview

Whenever a workflow needs to call out to an external system (most commonly a Send HTTP Request action), it needs credentials for that system. Without connection profiles, those credentials would be typed directly into each action, which means retyping a password in every workflow that calls the same ERP, and re-entering it everywhere if it changes.

A connection profile solves this by separating how to authenticate from what to send. Define the connection once, including any token-endpoint logic and caching, and every endpoint on it, and every workflow action calling those endpoints, authenticates through it.

A profile also owns the endpoints on that system: the individual operations Tagnet calls, each with its own path and body. Together they form three layers:

Layer	Answers	Configured
Connection profile	Which system, and how do we authenticate to it?	Once per external system
Endpoint	Which operation, at what path, sending what?	Once per operation
Workflow action	When do we call it?	Per workflow

Tip: Connection profiles are for Tagnet calling out to an external system. If you need an external system to call into Tagnet instead, see API Keys.

Permissions

Action	Required Role
View and manage connection profiles	Admin

Connection profile management is admin-only. Profiles are shared across your entire organization (the system scope); there is no per-site profile in this release.

The Connection Profiles Page

Open the Connection Profiles tab of the Integrations page (/integrations/profiles) to view all profiles.

The data grid shows:

Column	Description
Name	Descriptive label for the profile
Base URL	The host the profile sends to (the full URL on hover), which is what tells a test and a production profile apart
Authentication	The auth mode this profile uses
Endpoints	How many operations are defined on this system. A profile with none is authentication-only, which is valid
Status	The most serious thing true of the profile right now (hover for details)
Updated	When the profile was last changed

Status shows one of:

Status	Meaning
Secrets need re-entry	The stored secrets can no longer be decrypted; see Secrets Need Re-entry below
Rejecting	Tagnet has stopped sending to this system's host after repeated failures and will try again after a cooldown. See Diagnostics
Token failed	Token Endpoint profiles only: the most recent token request failed and none has succeeded since
Probing	Tagnet is sending a single test request to see whether the host has recovered
OK	No problems recorded

Use the search bar to filter by name or description. Click a row to open its detail page.

Authentication Modes

Mode	How it works
None	No authentication is added to outgoing requests
API key header	A static key value is sent in a header you name (e.g., X-Api-Key)
Basic auth	Standard HTTP Basic authentication: a username and password, base64-encoded in the Authorization header
Static bearer token	A fixed token value, sent per the configured header name and format
Token endpoint	Tagnet calls an endpoint to acquire a token, caches it, and renews it automatically before it expires

Choose Token endpoint for OAuth2-style client_credentials flows and similar systems that issue short-lived tokens. Choose one of the static modes when the external system uses a fixed, long-lived credential.

Every mode above is single-valued: it carries exactly one credential. If a system wants two at once, for example a bearer token from a token endpoint alongside a static API key header, pair the mode with a secret header: the mode covers one credential, secret headers cover any more.

Creating a Connection Profile

1. Click Add and choose Connection Profile.
2. Under Basics, enter a Name and optional Description. The name identifies the profile in pickers and lists; renaming it later is safe and never breaks the workflow actions that use it.
3. Under Server, optionally set a Base URL and any Default headers (see below). Both are optional; a profile with neither still works.
4. Under Authentication, choose an Authentication mode and fill in the fields it requires (see below).
5. Save.

Server: Base URL and Default Headers

The Base URL is the part every call to this system shares, such as https://erp.example.com. Endpoint paths are joined to it, so an endpoint whose path is /api/consume calls https://erp.example.com/api/consume.

Setting it is optional. Leave it blank and each endpoint carries a full URL of its own. Setting it is worth doing for two reasons:

• Endpoint paths stay short and readable, which is what you want in a picker and in a delivery list.
• Moving from TEST to PROD becomes one field on the profile instead of an edit to every endpoint.

An endpoint whose path is already a full URL (starting http:// or https://) ignores the base URL, so one unusual operation on a different host does not force you to give up the base URL for the rest.

Default headers are headers sent with every request made through one of this connection's endpoints, such as a required Accept or a vendor identifier. A workflow action still carrying its own pre-endpoint configuration does not send them until it is converted. An endpoint that sets a header with the same name overrides the default, since an operation that disagrees with a connection-wide header is being specific on purpose. Header name comparison is case-insensitive, as HTTP requires.

Credential-shaped header names are refused here: any name containing auth, token, secret, cookie, credential, or password, plus qualified key headers such as X-Api-Key, Access-Key, or Ocp-Apim-Subscription-Key. A name that merely ends in -Key is allowed, because those are routing metadata rather than secrets: Idempotency-Key, X-Correlation-Key, and Partition-Key all save normally. Credentials belong under Authentication below, either in the mode's own fields or as a secret header, where they are encrypted and never written into a delivery record.

Secret values (API keys, passwords, bearer tokens, token-endpoint credentials) are write-only. Once saved, a secret field shows blank with a "(set)" label rather than the stored value. Leave it blank to keep the current value, or type a new value to replace it. There is no way to retrieve a previously saved secret from the UI; if you have lost it, enter a new one.

API Key Header

Set a Header name (e.g., X-Api-Key) and the API key value. Tagnet sends the key exactly as entered in that header on every request.

Basic Auth

Set a Username and Password. Tagnet base64-encodes username:password into the standard Authorization: Basic ... header.

Static Bearer Token

Set the Bearer token value. Tagnet attaches it per the token placement settings below, in a header by default (which works with non-standard bearer schemes too), or in the request body for systems that expect it there.

Token Endpoint

This mode has the most configuration because it describes an entire token request/response cycle.

The Token request fields describe how Tagnet asks for a token:

Field	Description
Token URL or path	Where Tagnet POSTs the credential request. A path such as /oauth/token is joined to the profile's base URL; a full URL is used as-is, for an identity provider on a different host. A preview under the field shows the resolved URL
Request body format	JSON (a flat JSON object) or Form URL-encoded (e.g., standard OAuth2 client_credentials)
Request fields	Flat key/value pairs sent in the body, such as client_id, client_secret, or grant_type. Mark a field Secret to store its value encrypted instead of in plain configuration
Request headers	Static headers sent with the token request, such as a required Accept or vendor header

The Token response fields describe where Tagnet finds the token and how long it lasts:

Field	Description
Token path	The JSON property path to the token in the response, e.g. access_token
Token expiry	See the table below
Expiry path	The JSON property path to the expiry value (required unless expiry mode is "No expiry")
Refresh skew (seconds)	Renew the token this many seconds before its computed expiry, so a request never races an about-to-expire token. Defaults to 90

Token expiry modes:

Mode	Behavior
No expiry	The token is cached indefinitely and only refreshed reactively, if the external system later rejects it
Seconds until expiry	The response carries a countdown at the expiry path (e.g. expires_in). Accepts both JSON numbers and numeric strings, since some identity providers send this as a string
Absolute timestamp	The response carries an ISO 8601 timestamp at the expiry path. A timestamp with no timezone designator is always treated as UTC, never server-local time

Use Preview request at any point while editing to see the exact wire-format request Tagnet will send, with secret values masked. Use Test connection to run a real acquisition against the endpoint using the current (including unsaved) form values; the result shows whether a token was acquired and when it expires, or the exact failure reason.

Token on Data Requests

For Static bearer token and Token endpoint profiles, the Token on data requests section controls how the token is attached to the actual data request (as opposed to the token request itself). Choose where the token goes under Send the token:

Placement	Description
In a request header (default)	The token is sent in the header named by Header name (default Authorization), formatted by Header value format (default Bearer {token}; {token} is replaced with the static or acquired token). Change these for non-standard schemes, for example a system that expects X-Auth-Token: {token} with no Bearer prefix needs the header name changed to X-Auth-Token and the format changed to {token}.
In the request body	The token is set as a top-level property on the outgoing JSON body, named by Body field (e.g. Token). Some systems, a VMI queue API among them, authenticate a call by a token inside the payload rather than a header.

Requirements for body placement. Requests through this profile must send a JSON object body. A request with no body, a non-JSON body, or a non-JSON content type fails rather than going out with the credential missing: Tagnet never sends a request unauthenticated when it was configured to carry a token. Body field names a top-level property, not a nested path, since the systems that authenticate this way use a flat request body. If the body already has a property with that name, its value is replaced with the token.

The token is set on the body at send time, immediately before the request goes out. The request stored in the Integration Outbox or shown in workflow execution history never contains it, the same as a header-carried token is masked in those records.

Body placement is only available for Static bearer token and Token endpoint modes; API key header and Basic auth are header-shaped by definition.

Secret Headers

Some external systems want two credentials on every request at once. The motivating case is an ERP whose calls need a bearer token acquired from a token endpoint and a static APIKey header at the same time. The authentication mode above is single-valued, so it can only carry one of them. Secret headers close that gap: named credential headers, sent on every request through this connection, in addition to whatever the mode above contributes.

Secret headers work with any authentication mode, including None. A profile with mode None and one secret header is a complete way to model a system that authenticates with nothing but a single static header.

Under Authentication, click Add secret header to add a row, then fill in:

• Header name: the header the external system expects, for example APIKey.
• Value: the credential. Like every other secret field on this form, it is write-only: once saved, it shows blank with the label Value (set) instead of the stored value. Leave it blank to keep the current value, or type a new value to replace it.

Values are encrypted at rest and attached to the request immediately before it is sent. They are never written into a delivery record, unlike default headers, which are stored in clear text with every delivery. If a queued delivery in the Integration Outbox is retried after you rotate a secret header's value, the retry carries the new value, not the one that was current when the request was first queued.

Important: Renaming a secret header orphans its stored value. The stored secret is keyed by the header's name, so changing the name from APIKey to X-Api-Key doesn't rename the credential, it disconnects the row from it. The row goes back to reading Value instead of Value (set), and you need to re-enter the value under the new name.

Validation. Tagnet refuses to save a secret header that:

• Has no name.
• Duplicates another secret header. Header names are case-insensitive, so entries differing only in case collide too.
• Names the same header as a default header. The two are stored in different places, one encrypted and one clear text, so nothing downstream would catch the collision on its own.
• Names the header the profile's own authentication mode already writes to, for example a secret header called Authorization on a Static bearer token profile. The mode's credential is applied last and always wins that header, so a colliding secret header would simply never arrive; give it its own name instead.

Tagnet also warns, without blocking the save, when a secret header has the same name as a header one of the profile's endpoints sets. The secret header wins at send time, because a credential must beat a clear-text endpoint value, so that endpoint's own value never arrives. The warning names the endpoints involved; rename one side if the endpoint needs its own value. The endpoint editor shows the same warning from the other direction when a header there collides with an existing secret header.

If a secret header's value is missing or can't be decrypted, most often after an encryption key rotation, the request fails outright with a clear error rather than going out with the header silently missing. Tagnet never sends a request that was configured to carry a credential without that credential. See Secrets Need Re-entry below; the same recovery applies to secret headers as to any other secret on the profile.

Secret headers appear in an endpoint's request preview, listed by name with the value masked. See Headers and credentials in the Integration Endpoints guide.

The Connection Profile Detail Page

Open a profile to see its full configuration and, for Token Endpoint profiles, its live token state.

Two cards sit at the top:

• Deliveries, last 7 days: how many deliveries went through this profile, how many did not land, and the average endpoint response time. Click it to open the Analytics tab filtered to this profile.
• Endpoints: how many operations the profile defines. Click it to add one.

Secrets Need Re-entry

If a profile's stored secrets can no longer be decrypted, almost always because your server's encryption keys were rotated (see Rotate Keys), Tagnet flags the profile automatically instead of failing later with a misleading "not set" error. The flag is set the next time Tagnet reads the profile's secrets, which happens whenever a workflow action uses the profile, a token acquisition runs, or you open the profile to edit it, so a profile that has sat untouched since a rotation may not show the flag until one of those happens.

Once flagged:

• The Connection Profiles list shows a Secrets Need Re-entry chip next to the profile's name.
• This detail page opens with a warning banner at the top explaining what happened, with a Re-enter secrets button that jumps to the edit page.
• The edit page shows the same warning above the form. Secret fields below it still display (set), but those stored values are unrecoverable: type them in again and save to restore the connection.

A ConnectionProfileSecretsDecryptFailed security event is recorded once, at Critical severity, on the transition into the flagged state, not on every failed attempt afterward. The flag clears automatically as soon as you re-enter the profile's secrets and save; nothing else needs to be reset by hand. Copy carries the flag to the copy too, since copying carries over the same unreadable secret store; re-enter secrets on the copy as well.

Endpoints

The Endpoints section sits directly under the basics, because operations are what an operator comes here to work on: authentication is configured once and then mostly left alone. The table shows each endpoint's name, method, path, body content type, current version, how many workflow actions use it, and when it was last changed. Click a row to open the endpoint's own page, or use Edit and Copy in the row's Actions menu.

Add an endpoint from the Endpoints card at the top of the page, or Add endpoint in the Actions menu. A profile with no endpoints is authentication-only, which is a complete and valid setup for a system Tagnet only ever authenticates against.

See Integration Endpoints for the full guide, including versioning, rollback, and test sends.

Token Status

Token Endpoint profiles show a Token status panel with the current cache state:

• Cached token: whether a token is currently held in memory
• Acquired: when the cached token was fetched
• Expires: when it is due to be renewed
• Last failure: the most recent acquisition failure, if any, with the error message on hover

Actions available from this panel:

• Test connection: acquires a token using the profile's saved configuration and populates the cache, exactly as a workflow action would
• Clear token: discards the cached token so the next request re-acquires one from scratch
• Reveal token: displays the currently cached token on screen for troubleshooting. This is recorded as a security event (see Security below) and only available when a token is cached

Preview Request

For Token Endpoint profiles, Preview request shows the token request exactly as it will be sent on the wire: method, URL, headers, and body, with secret values masked as ••••••.

Used By

A table of every workflow action currently referencing this profile: the workflow, the action, the endpoint it sends to (Own request when the action names the profile directly and carries its own request), and whether the workflow is enabled. Click a row to open the workflow. Use this before editing or deleting a profile to understand its blast radius.

Duplicating a Profile

Click Copy in the actions menu to create a copy with the same configuration and secrets, named "Original Name (Copy)" (incrementing if that name is taken). This is the fastest way to set up a TEST/PROD pair: duplicate your working profile, then edit the copy's base URL and credentials for the other environment.

Endpoints are not copied with the profile. Duplicate the endpoints you need onto the copy from their own pages, or add them fresh.

Deleting a Connection Profile

Click Delete in the actions menu. If any workflow actions reference the profile, the confirmation dialog lists how many and warns that they will fail until reassigned. Connection profiles are referenced by id, not by a hard link, so deleting one does not block; it simply means the referencing Send HTTP actions start failing with a clear "profile not found" error the next time they run. Reassign or remove those actions before or immediately after deleting the profile.

Endpoints are the exception: they belong to the profile and are deleted with it, taking their version history with them. The confirmation says how many will go. Any workflow action sending to one of those endpoints fails on its next run.

Using a Profile in a Workflow

Both HTTP actions, Send HTTP Request and HTTP Integration (durable), are configured by picking an endpoint, not by entering a URL. The endpoint supplies the URL, headers, body and content type, and its profile supplies the authentication. The action stores the endpoint's id, so renaming the endpoint or the profile later never breaks the action. Actions created before endpoints existed keep their own configuration and keep working; see Converting an existing action.

There is no inline credential option on a new action and no separate "no authentication" setting. If the system needs no credentials at all, create a profile with Authentication set to None, rather than expecting a way to skip the profile entirely. A queued delivery is stored until it succeeds, so keeping credentials out of the action and resolving them fresh from the profile at send time is what keeps a secret from ever landing in a delivery record. For the same reason, credential-shaped header names are refused on durable actions and on endpoints; put those on the profile instead, either as the auth mode's own credential or as a secret header. The rule is the same one described under Server: Base URL and Default Headers above. See the Integration Outbox guide for the full behavior of the durable action.

If a request fails with 401 or 403 and the action is using a Token Endpoint profile, Tagnet assumes the cached token was rejected (revoked or expired server-side), refreshes it once, and retries the request automatically. This retry does not count against the action's configured Max Retries, which is reserved for transient failures like timeouts and 5xx responses.

Token acquisition uses the token endpoint's own per-host circuit breaker, separate from the data request's, so a failing identity provider pauses token calls without blocking healthy data endpoints (and vice versa). A timeout or server error from the token endpoint counts toward the token host's circuit breaker like any other outbound call, and can briefly pause new requests to it. A rejected credential, such as a 400 or 401 from a bad client secret, is treated as a configuration problem rather than evidence the host is unhealthy, so it never trips the breaker for other profiles that happen to share the same identity provider host. See Send HTTP Request for the full behavior.

Security

• Secrets are encrypted at rest. Connection profile secrets are stored encrypted, using the same key ring as device credentials, and are never returned by any read API or shown in the UI once saved.
• Acquired tokens are never persisted. Tokens live only in an in-memory cache on the server; only acquisition timestamps and failure messages are stored on the profile record.
• Tokens are never logged. Request previews, execution history, and application logs mask token and secret values.
• Concurrent requests share one acquisition. If multiple workflow actions need a token for the same profile at the same moment, only one acquisition call is made; the rest wait for and reuse its result.
• A decrypt failure is caught and flagged, not silently swallowed. If stored secrets can no longer be decrypted, most often after an encryption key rotation, Tagnet flags the profile rather than treating the secret as though it were never set. See Secrets Need Re-entry above.

Four connection-profile operations are recorded in the Security Events log: revealing a cached token, a failed token acquisition, a profile's secrets failing to decrypt, and deleting a profile. Deletion is logged because it is a hard delete: the row and its created/updated audit fields go with it, so the security event is the only surviving record of who removed a credential-holding profile.

Repeated failures are recorded once, not once per attempt. Every delivery through a profile retries token acquisition, so a failure that does not fix itself, a rotated key ring or a wrong client secret, would otherwise write a ConnectionTokenAcquireFailed event on every attempt for as long as the integration keeps running. Tagnet records one event per failure episode instead. A new event is recorded when acquisition succeeds and then fails again, or when you edit the profile and it still fails, since both mean something genuinely changed. The profile's own Last token status always shows the most recent failure and its message regardless.

Creating and editing a profile are not currently logged. Endpoint changes are not either, though every change to what an endpoint sends is recorded in its own version history with the author and timestamp.

Best Practices

• Use Token Endpoint mode for OAuth2-style APIs. Letting Tagnet manage acquisition and renewal is more reliable than a long-lived static token that eventually expires unnoticed.
• Name profiles by system and environment, e.g. "Acme ERP (Production)" and "Acme ERP (Test)," especially if you duplicate a profile for a TEST/PROD pair.
• Check Used By before deleting. A profile with active usages will break those workflow actions immediately on the next run.
• Watch the Token Status panel after changing credentials. Editing a profile invalidates its cached token, so the next request re-acquires; confirm it succeeds with Test connection rather than waiting for a workflow to hit the failure.
• Use Preview request to debug integration setup, especially field names and body format, before troubleshooting on the external system's side.

Frequently Asked Questions

Q: Can I see a secret I already saved? A: No. Secret values are write-only above the storage layer. If you need to confirm a value, use Preview request (which shows the field is set, masked) or re-enter it.

Q: What happens to a workflow action if I delete the connection profile it uses? A: The action fails at run time with a message that the profile was not found. It does not fail silently, and it does not block the delete. Reassign the action to a different profile or remove it.

Q: Does renaming a profile break anything? A: No. Workflow actions reference profiles by internal id, not by name, so renaming is always safe.

Q: Can I send two credentials on the same request, like a bearer token and a static API key? A: Yes. Set the authentication mode to whichever credential fits it, Token endpoint for the bearer token in that example, then add the other as a secret header. Both are attached to every request through the profile.

Q: Why is Test connection unavailable for API key, Basic auth, or Static bearer profiles? A: Those modes have no acquisition step to test; the value you enter is sent as-is. Any problem with them (wrong key, expired token) only surfaces when a workflow action actually uses the profile against the real endpoint.

Q: What is the refresh skew for? A: It renews the token slightly before its reported expiry (90 seconds by default) so a request in flight never races the exact expiry moment and gets rejected mid-call.

Q: A profile shows "Secrets Need Re-entry" but nobody touched it. What happened? A: Your server's encryption keys were rotated (see Rotate Keys), which is by far the most common cause; the previously stored secrets can no longer be decrypted under the new keys. Re-enter the profile's secrets on its edit page and save; the flag clears automatically.