The Identity Server comes first

The File Service does not have its own user accounts, sign-in or client registry. It runs on the CCS Identity Server, so you set that up before you call the service. This page explains the split of responsibilities and points you to the checklist.

What the Identity Server owns

Everything about who people are and what they may reach lives in the Identity Server.

Owned by the Identity Server	What it means for the File Service
Users and sign-in	A user signs in once. The service never sees a password.
Tenants and memberships	A user can belong to several tenants. The service serves only active members.
Roles	Tenant roles and your own application roles. Which role may do what with files is stored with the roles, per application: the tenant owner edits it on the Files console’s Permissions page.
Applications	Your tenant applications, and the File Service itself as a platform application called Files.
Clients	The OAuth clients that sign users in, and the backend client your server uses.
Scopes and resources	The Files API is a resource with the scopes files:access, files:manage, files:read and files:config.manage, and eleven files.* permission keys.
Tokens	Every token the service accepts is issued by the Identity Server, including the exchanged user tokens.

What the File Service owns

The service owns the files and everything about them, and nothing else.

• The bytes, their versions and renditions, and the signed URLs that move them.
• Folders, metadata, tags, your external references, search.
• The access entries on folders and files, share links, the trash, quotas and the audit log.
• The Files console, where members browse and administrators set things up.

It stores no passwords and issues no tokens. It knows nothing about your business: a rule such as “only the author may attach media to a post” stays in your backend, which calls the service after it has checked.

What the service expects from it

Four things must be true at the Identity Server before a call can succeed.

1. A valid token for the Files API. The token is signed by the Identity Server, has the audience files-api and carries files:access (users) or a backend scope (files:manage, files:read, files:config.manage). A token for your own API, for Chat or for Notifications is rejected with invalid_token. The resource identifier your backend sends in a token request is https://files.centralcodestation.com/api. Central Code Station operates the resource; you do not create it.
2. A context. Every call names a tenant and a tenant application in the URL. The user must be an active member of the tenant (not_tenant_member) and have access to the application (no_application_access).
3. A client bound to your application. A token issued to your application’s client works only in that application. Any other context answers client_context_mismatch.
4. Files switched on for your application. A tenant administrator can switch the Files platform application off per application. The service then answers 403 files_access_not_granted on every route.

Two more depend on what you build:

• A token-exchange permission for your backend client, with files:access on the Files API, if your app ever calls the service as the user. In the backend-mediated upload flow of the quickstart it never does.
• Your web origins. A browser that calls the API needs its origin in the allowed origins of your application’s web client at the Identity Server. Uploads and downloads go to signed URLs, which accept any origin.

Bearer tokens only

The service accepts Bearer tokens. A token bound to a key (DPoP), as some mobile Identity Server integrations issue for your own API, is refused. Your mobile app reaches the File Service through your backend: either your backend calls the service, or it exchanges the user’s token and hands out a plain Bearer token.

If the Identity Server is unavailable

The service reuses recent answers from the Identity Server for a short time. When it cannot reach the Identity Server and has no recent answer, it responds with 503 identity_unavailable.

• Treat it as a temporary failure, not as a permission problem. Retry with a back-off.
• Your backend client also needs the Identity Server to get tokens, so new tokens fail during the same outage.
• Signed URLs already handed out keep working until they expire: they do not involve the Identity Server.

Where the Identity Server documentation lives

The Identity Server has its own documentation. These pages repeat every step you need to integrate, and link there for background and depth.

Identity Server documentationArchitecture, OAuth flows, clients, roles and the admin UI. Opens in a new tab.

Token exchangeSetup, the backend route, rules and troubleshooting for the exchange a user token depends on.

If a link does not open for you, ask your Identity Server administrator for access.

Next step

Work through the prerequisite checklist. It lists what to create in the Identity Server admin UI and how to verify each step. The glossary defines the terms.