Delivery accounts

Your organization has its own SFTP endpoint (see Catalog.sftpHost). A delivery account is a login on that endpoint, issued to one of your senders — a label or a distributor. Senders are not //SCHEMA users; they have no console access, only the account.

Accounts authenticate with SSH keys, a password, or both. Keys are recommended: an account created without a password cannot sign in until you add a key. Changes to passwords and keys take effect on the sender's next connection.

See Manage SFTP delivery accounts.

Operations

querydeliveryAccounts
querydeliveryAccountKeys
mutationissueDeliveryAccount
mutationresetDeliveryPassword
mutationrevokeDeliveryAccount
mutationaddDeliveryKey
mutationrevokeDeliveryKey
mutationsetSftpHost

The DeliveryAccount object#

An SFTP login issued to one of your senders. Never includes a secret.

Attributes

deliveryAccountPkInt!
Unique identifier.
usernameString!
The SFTP login name.
displayNameString!
Who the account is for, e.g. Lanternfish Records.
hasPasswordBoolean!
Whether the account has a password.
keyCountInt!
Live SSH keys. 0 with no password means the account cannot sign in yet.
createdAtDateTime!
When it was issued.
lastSeenAtDateTimenullable
Approximately when something last arrived on it.
revokedAtDateTimenullable
When access was withdrawn, or null.

The DeliveryKey object#

An SSH public key authorized on a delivery account, identified by fingerprint.

Attributes

deliveryAccountKeyPkInt!
Unique identifier.
fingerprintString!
OpenSSH SHA256: fingerprint — compare with ssh-keygen -lf on the sender's machine.
createdAtDateTime!
When it was added.
revokedAtDateTimenullable
When it was revoked, or null.

The IssuedAccount object#

A newly issued delivery account.

Attributes

deliveryAccountPkInt!
Unique identifier.
usernameString!
The SFTP login name.
passwordStringnullable
The generated password, shown once. null for a key-only account.

The IssueDeliveryAccountInput input object#

An SFTP account to issue.

Fields

usernameString!required
The login. 3–32 characters: a lowercase letter, then a–z, 0–9, _ or -. Unique on your endpoint.
displayNameString!required
Who it is for, e.g. Coastline Sound.
catalogPkInt
The catalog its deliveries land in. Must belong to your organization. Defaults to the caller's catalog.
withPasswordBoolean
Generate a password. Defaults to false — key-only.

List delivery accounts#

querydeliveryAccounts→[DeliveryAccount!]!config_read

Every SFTP login your organization has issued, newest first, including revoked ones.

Arguments

None.

Returns

A list of DeliveryAccount objects.

Request

query {
  deliveryAccounts {
    deliveryAccountPk
    username
    displayName
    hasPassword
    keyCount
    lastSeenAt
    revokedAt
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  deliveryAccounts {\n    deliveryAccountPk\n    username\n    displayName\n    hasPassword\n    keyCount\n    lastSeenAt\n    revokedAt\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        deliveryAccounts {
          deliveryAccountPk
          username
          displayName
          hasPassword
          keyCount
          lastSeenAt
          revokedAt
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "deliveryAccounts": [
      {
        "deliveryAccountPk": 64,
        "username": "lanternfish",
        "displayName": "Lanternfish Records",
        "hasPassword": false,
        "keyCount": 2,
        "lastSeenAt": "2026-09-17T08:51:40.221903+00:00",
        "revokedAt": null
      }
    ]
  }
}

List an account's keys#

querydeliveryAccountKeys→[DeliveryKey!]!config_read

The public keys authorized on one delivery account, by fingerprint. An account that is not yours returns an empty list.

Arguments

deliveryAccountPkInt!required
The delivery account.

Returns

A list of DeliveryKey objects.

Request

query {
  deliveryAccountKeys(deliveryAccountPk: 64) {
    deliveryAccountKeyPk
    fingerprint
    createdAt
    revokedAt
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  deliveryAccountKeys(deliveryAccountPk: 64) {\n    deliveryAccountKeyPk\n    fingerprint\n    createdAt\n    revokedAt\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query {
        deliveryAccountKeys(deliveryAccountPk: 64) {
          deliveryAccountKeyPk
          fingerprint
          createdAt
          revokedAt
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "deliveryAccountKeys": [
      {
        "deliveryAccountKeyPk": 118,
        "fingerprint": "SHA256:q1v0mZcX9y5b3kR2nTwL8dPfHgJ4sA6eU7oIcBxYzQk",
        "createdAt": "2026-06-02T14:10:33.500112+00:00",
        "revokedAt": null
      }
    ]
  }
}

Issue a delivery account#

mutationissueDeliveryAccount→IssuedAccount!config_write

Create an SFTP login on your endpoint. By default the account has no password and cannot sign in until you add a key. Pass withPassword: true to generate a password, returned once.

Arguments

inputIssueDeliveryAccountInput!required
The account to issue.
Show child parameters
- usernameString!required
  The login. 3–32 characters: a lowercase letter, then a–z, 0–9, _ or -. Unique on your endpoint.
- displayNameString!required
  Who it is for, e.g. Coastline Sound.
- catalogPkInt
  The catalog its deliveries land in. Must belong to your organization. Defaults to the caller's catalog.
- withPasswordBoolean
  Generate a password. Defaults to false — key-only.

Returns

An IssuedAccount.

Request

mutation {
  issueDeliveryAccount(
    input: { username: "coastline", displayName: "Coastline Sound", withPassword: true }
  ) {
    deliveryAccountPk
    username
    password
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  issueDeliveryAccount(\n    input: { username: \"coastline\", displayName: \"Coastline Sound\", withPassword: true }\n  ) {\n    deliveryAccountPk\n    username\n    password\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        issueDeliveryAccount(
          input: { username: "coastline", displayName: "Coastline Sound", withPassword: true }
        ) {
          deliveryAccountPk
          username
          password
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "issueDeliveryAccount": {
      "deliveryAccountPk": 71,
      "username": "coastline",
      "password": "C9HWT-R2QV8-MZE4K-J6DXS"
    }
  }
}

Reset a delivery password#

mutationresetDeliveryPassword→String!config_write

Replace an account's password with a generated one. The old password stops working immediately; the new one is returned once.

Arguments

deliveryAccountPkInt!required
The delivery account.

Returns

The new password.

Request

mutation {
  resetDeliveryPassword(deliveryAccountPk: 71)
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  resetDeliveryPassword(deliveryAccountPk: 71)\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        resetDeliveryPassword(deliveryAccountPk: 71)
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "resetDeliveryPassword": "QM4TX-E7VRB-2NK9W-5GHAP"
  }
}

Revoke a delivery account#

mutationrevokeDeliveryAccount→Boolean!config_write

Withdraw an account's access. It stays listed with revokedAt set, and what it delivered keeps its history. Revoking twice keeps the first timestamp.

Arguments

deliveryAccountPkInt!required
The delivery account.

Returns

true on success.

Request

mutation {
  revokeDeliveryAccount(deliveryAccountPk: 71)
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  revokeDeliveryAccount(deliveryAccountPk: 71)\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        revokeDeliveryAccount(deliveryAccountPk: 71)
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "revokeDeliveryAccount": true
  }
}

Add a delivery key#

mutationaddDeliveryKey→DeliveryKey!config_write

Authorise an SSH public key on an account. Several keys can be live at once, which makes rotation gapless: add the new key, confirm the sender can connect, then revoke the old one.

Arguments

deliveryAccountPkInt!required
The delivery account.
publicKeyString!required
One authorized_keys line from the sender, e.g. ssh-ed25519 AAAAC3Nza… ops@lanternfish.

Returns

The new DeliveryKey.

Request

mutation AddKey($key: String!) {
  addDeliveryKey(deliveryAccountPk: 64, publicKey: $key) {
    deliveryAccountKeyPk
    fingerprint
  }
}

Variables

{
  "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHk3b2l0Z0N6c1l4b3dQZ2pQb0VlQ3ZkR2Z0T2xY ops@lanternfish"
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation AddKey($key: String!) {\n  addDeliveryKey(deliveryAccountPk: 64, publicKey: $key) {\n    deliveryAccountKeyPk\n    fingerprint\n  }\n}",
  "variables": {
    "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHk3b2l0Z0N6c1l4b3dQZ2pQb0VlQ3ZkR2Z0T2xY ops@lanternfish"
  }
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation AddKey($key: String!) {
        addDeliveryKey(deliveryAccountPk: 64, publicKey: $key) {
          deliveryAccountKeyPk
          fingerprint
        }
      }
    `,
    variables: {
      "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHk3b2l0Z0N6c1l4b3dQZ2pQb0VlQ3ZkR2Z0T2xY ops@lanternfish"
    },
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "addDeliveryKey": {
      "deliveryAccountKeyPk": 131,
      "fingerprint": "SHA256:7GmU2cQkV1xYp9sLbT3rNfWd8hKzE4aJ6oXiRyCvB0M"
    }
  }
}

Revoke a delivery key#

mutationrevokeDeliveryKey→Boolean!config_write

Withdraw one key. Other keys on the account keep working.

Arguments

deliveryAccountKeyPkInt!required
The key to revoke.

Returns

true on success.

Request

mutation {
  revokeDeliveryKey(deliveryAccountKeyPk: 118)
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  revokeDeliveryKey(deliveryAccountKeyPk: 118)\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        revokeDeliveryKey(deliveryAccountKeyPk: 118)
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "revokeDeliveryKey": true
  }
}

Set the SFTP hostname#

mutationsetSftpHost→[DeliveryAccount!]!config_write

Record your organization's SFTP hostname, e.g. halcyon.ftp.schema.fm. This records what senders should connect to; it does not itself provision DNS. Pass null to clear it.

Arguments

hostString
A bare hostname — no scheme, no port. Lowercased. Must not be in use by another organization.

Returns

Your organization's DeliveryAccount list, unchanged.

Request

mutation {
  setSftpHost(host: "halcyon.ftp.schema.fm") {
    username
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "mutation {\n  setSftpHost(host: \"halcyon.ftp.schema.fm\") {\n    username\n  }\n}"
}
EOF

const res = await fetch("https://api.schema.fm/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      mutation {
        setSftpHost(host: "halcyon.ftp.schema.fm") {
          username
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "setSftpHost": [
      { "username": "lanternfish" },
      { "username": "coastline" }
    ]
  }
}