Connect an APIC

With the MIM loaded, Fabrik understands the shape of ACI — every class, every property, every containment rule. What it needs next is a way in: a set of credentials for a live APIC controller it can query on your behalf.

An APIC connection is a named record holding a URL, a username, and a Fernet-encrypted password. Once it's saved, the query builder can run against it, and AWX validation rules can use it to read state. You can have as many connections as you need — one per fabric, plus whatever you set up for labs.

Crucially, the connection and the MIM are independent. Swap the MIM when you upgrade your fabric; swap the connection when you rotate credentials. Neither action disturbs the other.

Who can create connections

Creating a new APIC connection is admin-only. Non-admins see the connection list, can test the connections that are shared with them, and use public ones in the query builder — but the form rejects any create attempt with a permission error. Ask your admin to add the fabric on your behalf the first time.

The page lives at Settings → APIC Connections (sidebar) or directly at /settings/connections.

Before you start

Have these on hand before you open the form:

The APIC base URL, including https:// — for example https://apic.lab.example.com. Don't append /api or a specific path; Fabrik adds those itself.
A service account with a password, not a session token. For pure query-builder use, a read-only role is enough. If you also plan to drive AWX validations that push configuration, pick an account with the appropriate write privileges.
Whether your APIC presents a trusted certificate or a self-signed one. That decides the Verify SSL toggle.

Using a dedicated service account rather than a personal login keeps audit trails clean and survives staff changes.

Creating a connection

Click "Add Connection"

The button sits at the top-right of the APIC Connections section. If there are no connections yet, the empty state also has an Add Your First Connection button — it opens the same dialog.

Fill in the form

The dialog has a compact set of fields:

Name (required) — a human label you'll recognise in dropdowns. "Production Fabric", "DC1 Lab", etc.
Description (optional) — free text. A sentence about what this fabric is for is worth the five seconds.
URL (required) — the APIC base URL with scheme: https://apic.example.com. The field is typed as a URL, so the browser will complain if you forget https://.
Username (required) — the APIC login, not an email.
Password (required) — click the eye icon on the right to reveal what you've typed.
Verify SSL certificates — off by default. Leave it off for labs using self-signed certs, turn it on for any fabric with a trusted cert where you want full chain validation. See the note below before shipping to production.
Make public (all users can use) — visibility toggle. Off means only you and admins can see this connection; on means every authenticated Fabrik user can pick it in the query builder.

Save

Click Create. The password is Fernet-encrypted with your instance's ENCRYPTION_KEY before it hits PostgreSQL — it's never stored in plaintext, and it never comes back out in API responses.

Save does not test the connection. That's the next step.

Test

Back on the list page, click Test on the newly-created row. Fabrik logs in against the live APIC with the stored credentials and either shows a green check with "Connection successful" or a red X with the exact error message from the controller.

A successful result auto-clears after five seconds; failures stick around until you dismiss them or test again. The button doubles as a cancel — click it while a test is in flight to abort.

About Verify SSL in production. Turning this off means Fabrik won't validate the certificate chain on every request — convenient for labs, unwise for anything holding production data. For production fabrics, install a properly-signed APIC certificate (or your internal CA's) and leave Verify SSL on.

Visibility: private vs. public

Each connection is either private or public:

Visibility	Who sees it in the query builder
Private (default)	The creator, plus administrators.
Public (`Make public` checked)	Every authenticated user on this Fabrik instance.

There's no per-user sharing list in the current UI — it's a simple binary. In practice this works cleanly: lab fabrics tend to be public so the team can explore freely, while production connections stay private and run through scheduled queries or saved templates that the admin provisions.

You can flip the toggle later by editing the connection.

Testing an existing connection

Every connection card has a Test button, regardless of visibility. Testing:

Logs in to the APIC with the stored credentials
Updates the persisted Last tested status and message on the connection
Surfaces the result inline — the card stores the most recent test outcome, so you can see at a glance whether a fabric is reachable without re-testing

If a connection that worked yesterday fails today, the message will usually tell you why: expired password, APIC unreachable, certificate changed, and so on. See Troubleshooting for the patterns.

Editing and deleting

Edit and Delete buttons appear on connection cards only when you're allowed to use them — the owner and administrators see them; other users don't.

Edit pre-fills every field except the password. Leave the password blank to keep the existing one; type a new one to rotate it. The name, URL, username, SSL setting, and visibility are all editable.

Delete asks for confirmation. Deleting a connection that's referenced by saved queries or scheduled tasks breaks those executions — they'll fail on their next run until you point them at a different connection. Review the usage in Library and Task Management before deleting anything with a long history.

What happens behind the scenes

A few details worth knowing, since they explain behaviour you'll see later:

Encryption at rest — the password is encrypted using the Fernet scheme with your instance's ENCRYPTION_KEY. Rotating that key invalidates every stored password, so don't rotate it casually.
Session reuse — Fabrik caches the APIC authentication token per connection and refreshes it automatically before it expires (APIC tokens live roughly ten minutes). You don't need to re-test before every query.
Test ≠ saved — the Test button runs a real login against APIC; a test failure doesn't invalidate a saved connection. Use it as a health check, not a precondition for saving.
Audit trail — create, update, delete, and every test attempt are written to the audit log with the acting user, timestamp, and outcome. Admins can review them in Administration → Audit Logs.

Troubleshooting

Common connection issues and what they usually mean:

401 Unauthorized. Wrong username or password, or the APIC account is locked. Log in to APIC directly with the same credentials to confirm.
SSL certificate verify failed. You have Verify SSL on but APIC is presenting a self-signed or otherwise untrusted certificate. Either install a trusted cert on APIC (preferred for production) or turn off Verify SSL (acceptable for labs only).
Connection timeout / unreachable. The backend container can't reach the APIC URL. Check firewall rules, DNS resolution from inside the container, and that APIC itself is up.
"Failed to decrypt password." The ENCRYPTION_KEY in .env doesn't match the one that was in place when the connection was saved. Either restore the original key or re-create the connection with fresh credentials.
Test succeeds, but queries return empty. The account works but doesn't have read access to the objects you're querying. Widen the APIC role, or check that the tenant/object actually exists.

With a connection saved and tested green, you have everything you need to build something real. Continue to Run your first query to put the canvas to work.

Connect an APIC

On this page