Viewer and catalog

Every credential acts on exactly one catalog, chosen when the credential was issued. These two queries tell you which — and what the credential may do there. viewer is the cheapest way to check that a key works.

Operations

queryviewer
querycatalog

The Viewer object#

The credential that made the request.

Attributes

actorTypeString!
api_key for an API key, user for a signed-in person.
userPkIntnullable
The signed-in user's id. null for an API key.
orgPkInt!
The organization the credential belongs to.
catalogPkInt!
The catalog every request with this credential acts on.
scopes[String!]!
The scopes this credential holds. Note the spelling: this field returns names like CatalogRead, while ApiKey.scopes, grantableScopes and mintApiKey use the wire spelling catalog_read.

The Viewer object

{
  "actorType": "user",
  "userPk": 1001,
  "orgPk": 12,
  "catalogPk": 31,
  "scopes": ["CatalogRead", "CatalogWrite", "ConfigRead", "ConfigWrite", "MediaRead", "MediaWrite"]
}

The Catalog object#

The catalog a credential acts on — your isolation boundary — and its organization.

Attributes

catalogPkInt!
Unique identifier.
slugString!
Short, URL-safe name.
displayNameString!
Human-readable name.
orgPkInt!
The owning organization's id.
orgSlugString!
The owning organization's short name.
orgDisplayNameString!
The owning organization's human-readable name.
sftpHostStringnullable
The address your partners connect to: your endpoint's reserved IP address (e.g. 203.0.113.24), which stays the same for as long as you have the endpoint so partners can allow it through their firewalls. null until your endpoint is ready, or if your organization does not receive deliveries over SFTP — see sftpEndpointStatus.
sftpPortInt!
The port the SFTP endpoint listens on. 22 in production.
sftpEndpointStatusString!
Where your SFTP endpoint stands: ready (sftpHost is set), provisioning (requested and being set up — usually a few minutes for a new organization; sftpHost is null until it is ready), delayed (setup hit a problem and is retrying on its own), off (your endpoint existed and has been turned off — for example after canceling a trial; sftpHost is null), or none (your organization does not receive deliveries over SFTP).

The Catalog object

{
  "catalogPk": 31,
  "slug": "halcyon",
  "displayName": "Halcyon Audio",
  "orgPk": 12,
  "orgSlug": "halcyon",
  "orgDisplayName": "Halcyon Audio",
  "sftpHost": "203.0.113.24",
  "sftpPort": 22
}

Retrieve the viewer#

queryviewer→Viewer!any credential

Describes the credential that made the request: whether it is an API key or a signed-in user, which organization and catalog it acts on, and the scopes it holds.

Requires a valid credential but no particular scope, so a caller can always find out what it holds.

Arguments

None.

Returns

A Viewer.

Request

query {
  viewer {
    actorType
    orgPk
    catalogPk
    scopes
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  viewer {\n    actorType\n    orgPk\n    catalogPk\n    scopes\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 {
        viewer {
          actorType
          orgPk
          catalogPk
          scopes
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "viewer": {
      "actorType": "api_key",
      "orgPk": 12,
      "catalogPk": 31,
      "scopes": ["CatalogRead", "MediaRead"]
    }
  }
}

Retrieve the catalog#

querycatalog→Catalogcatalog_read

The catalog this credential acts on, with its organization and the organization's SFTP endpoint.

There is no argument: the catalog always comes from the credential, never from the request.

Arguments

None.

Returns

A Catalog, or null if the catalog no longer exists.

Request

query {
  catalog {
    slug
    displayName
    orgDisplayName
    sftpHost
    sftpPort
  }
}

curl https://api.schema.fm/graphql \
  -H "Authorization: Bearer $SCHEMA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "query": "query {\n  catalog {\n    slug\n    displayName\n    orgDisplayName\n    sftpHost\n    sftpPort\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 {
        catalog {
          slug
          displayName
          orgDisplayName
          sftpHost
          sftpPort
        }
      }
    `,
  }),
});
const { data, errors } = await res.json();

Response

{
  "data": {
    "catalog": {
      "slug": "halcyon",
      "displayName": "Halcyon Audio",
      "orgDisplayName": "Halcyon Audio",
      "sftpHost": "203.0.113.24",
      "sftpPort": 22
    }
  }
}