Gateway Principals and Logins

Updated Jul 26, 2026

Hosted File Gateway

Gateway Principals and Logins

A principal is who a connection acts as. It fixes the company, the storage root, and which routes apply. A credential is the auth material that resolves to one. A principal may hold several credentials — for rotation, or because two systems on the partner's side connect differently.

Both live on the Principals tab. Creating a principal needs DataMagik - Builder; adding a credential needs Builder or DataMagik - Security, because a credential is a secret even when the form only ever writes it.

The Principals tab with a certificate credential being added: type, certificate authority and identity

Creating a principal

Open Principals and give it a name — usually the partner's name.
Choose a kind:
- External partner — another company. Gets a locked single-partner root; org-to-org isolation is the invariant the whole design is built around. Link it to a trading partner to enable collect-from-gateway delivery.
- Our own system — one of your machines or applications.
Press Create. A storage root is assigned automatically and shown on the card.

The storage root is derived, never typed. It is the thing that confines every path the principal can reach, so it is not accepted from the browser. A principal without one is refused at login rather than defaulting to somewhere broad.

Deleting a principal removes it and its credentials but keeps every file it ever sent. Those are the record of what a partner actually delivered, and revoking a login should not erase history.

Authentication methods

Method	Protocol	Resolved by
Password	SFTP, FTPS	Username, compared against a stored hash. Minimum 12 characters.
SSH key	SFTP	Key fingerprint. No secret is stored at all.
SSH certificate	SFTP	A certificate signed by a trusted CA, carrying the identity this credential requires.
X.509 certificate	FTPS	A certificate chaining to a trusted CA; expiry and revocation checked.

All four are created the same way, from the Add credential row on a principal's card. The row changes to ask for what the chosen method actually needs.

Adding a password login

On the principal's card, type a username.
Leave the type as Password and enter one of at least 12 characters.
Press Add.

Usernames are globally unique across the whole endpoint. There is one shared endpoint, and the username is all the server has before it knows which tenant is connecting. A collision is reported as a collision rather than silently attached to the wrong principal. Prefix them — acme-steel-po, not ftp.

Adding an SSH key login

Ask the partner to generate a key pair and send you the public half only:

ssh-keygen -t ed25519 -C "acme-steel-gateway"
cat ~/.ssh/id_ed25519.pub

Paste that line into the credential field with type SSH key. It looks like ssh-ed25519 AAAAC3Nza… acme-steel-gateway. DataMagik stores the fingerprint; there is no secret at rest on either side.

Prefer keys to passwords for machine-to-machine transfers. Nothing has to be rotated on a schedule, nothing can be guessed, and nothing has to be sent to the partner over a channel you do not control.

Adding a certificate login

A certificate credential trusts a certificate authority rather than one specific key, which is what lets a partner rotate their own keys without telling you every time.

Create or register the CA first, on the Security tab — an issuing CA of your own, or the partner's.
On the principal, type a username and choose SSH certificate (SFTP) or X.509 certificate (FTPS).
Pick the certificate authority. The picker only offers CAs of the matching kind — SSH CAs for an SSH certificate, X.509 CAs for FTPS — and tells you which one to create if there is none yet.
Enter the certificate identity: the principal name inside the certificate that this credential will accept.
Press Add.

The identity is checked on every connection. A certificate signed by the right CA but carrying a different identity is refused — a mismatch never silently grants a different principal.

Issuing a certificate from your own CA

If the CA is one you generated, you can issue the partner's certificate yourself. On the Security tab, each of your issuing CAs carries an Issue certificate action:

Enter the identity — the same value you put on the credential.
Set the validity in days (365 by default, 730 maximum).
Press Issue certificate.

The private key is shown once and is never stored. Copy both the certificate and the private key and send them to the partner over a channel you trust, before you navigate away. If you lose them, issue another certificate — there is no way to recover the key, by design.

To withdraw a certificate before it expires, revoke it — see Trust & Certificates.

Restricting where a login may connect from

A credential can carry an IP allowlist of bare addresses or CIDR ranges. A malformed entry denies rather than being skipped — somebody who typed a bad CIDR meant to restrict access, and quietly ignoring it would grant exactly what they were trying to prevent.

Why every login is a service account

There is no human sign-in path to the gateway, on purpose. External partners and your own systems have the same shape: a credential resolves to a principal, which fixes a company and a scope. One authentication model means one place for isolation to be correct, rather than a matrix of special cases.

Consequences worth stating: gateway logins are not DataMagik user accounts, they do not appear in User Management, they have no permissions and cannot sign in to the web application, and SSO does not apply to them.