Skip to content
CCS Files Docs

Prerequisite checklist

Work through this checklist once for each tenant application. You need only this page and the Identity Server admin UI. Each step says where to click, links to more depth, and ends with a check.

Who needs which step

Section titled “Who needs which step”

Steps 1 to 5 apply to every integration. The others depend on what you build.

Step Backend-mediated uploads (the quickstart) Your app calls the service as the user Administrator
1. Tenant and members yes yes yes
2. Your tenant application yes yes yes
3. Files switched on yes yes yes
4. The Files API resource operated by CCS operated by CCS operated by CCS
5. A backend client with files:manage yes yes no
6. The token-exchange permission no yes no
7. Web origins no yes, for web apps no
8. Who may do what optional yes yes
9. The application’s settings recommended recommended yes
10. Values you need yes yes no

The steps

Section titled “The steps”

  1. A tenant exists and your users are members of it.

    In the Identity Server admin UI, open Tenants, pick your tenant and open Members. If the application only admits assigned users, assign each user to it as well. Without access the service answers not_tenant_member or no_application_access.

    Verify: a member can sign in to the Identity Server.

  2. Your tenant application exists in that tenant.

    Files, folders, settings and the audit log live inside your application, for example your social app. Create it under Applications if it does not exist. Files is a platform application and is never one of your applications.

    Verify: the application is listed for the tenant and is ACTIVE.

  3. Files is switched on for your application.

    Files is available to every tenant application unless a tenant administrator switched the Files platform application off for it (Applications, your application, Platform Apps). Check that it has not been. When it is off, the service answers 403 files_access_not_granted on every route, for your own clients as well.

    Verify: with the machine token of step 5 in FILES_TOKEN, GET /tenants/:tenant_id/applications lists your application with files_enabled: true:

    Terminal window
    curl -s "$FILES_API_URL/tenants/$CCS_TENANT_ID/applications" -H "Authorization: Bearer $FILES_TOKEN"
    # {"items":[{"application_id":"fitness-app","name":"Fitness","slug":"fitness","type":"TENANT","files_enabled":true}]}

  4. The Files API resource is registered.

    Central Code Station operates this for you; you do not create it. Its values are fixed, and you need them in your configuration. Clients send the identifier as resource=. Only the service reads the audience, in the token’s aud claim.

    Value Setting
    Identifier (resource=) https://files.centralcodestation.com/api
    Audience (aud) files-api
    User scope files:access
    Machine scopes files:manage (everything on content), files:read (reads and URLs), files:config.manage (settings and audit)
    Permission keys files.view, files.download, files.edit, files.share, files.delete, files.approve, files.manage, files.configure, files.settings.manage, files.audit.read, files.permissions.manage. See Permissions

    Never send files-api as resource=: the Identity Server finds the resource by its identifier. See Contexts and tokens.

    Verify: step 5 returns a token whose aud is files-api.

  5. A backend client with files:manage.

    In Clients, pick your application and create a client such as “Fitness Files Backend”, or reuse the backend client you already have for Chat or Notifications. Set it to CONFIDENTIAL and tick the grant type client_credentials. Open Resource Permissions, pick the Files API resource and grant files:manage (or files:read for a backend that only reads). Granting a permission on a platform resource needs a platform administrator. Keep the secret on your server and never ship it to a browser or an app. A deployment script that changes the application’s settings from code gets files:config.manage on a client of its own.

    Verify: a client_credentials call returns a token whose aud is files-api:

    Terminal window
    curl -s -X POST "$CCS_ISSUER_URL/oauth/token" -u "$CCS_FILES_CLIENT_ID:$CCS_FILES_CLIENT_SECRET" \
      --data-urlencode "grant_type=client_credentials" \
      --data-urlencode "scope=files:manage" \
      --data-urlencode "resource=$FILES_API_RESOURCE" > token.json
    jq -r '.access_token | split(".")[1] | @base64d | fromjson | {aud, scope}' token.json
    # { "aud": "files-api", "scope": "files:manage" }

  6. The token-exchange permission. (only when your app calls the service as the user)

    Token exchange is an Identity Server setting that its operator turns on. Ask your operator, or read the token exchange guide. Then open your backend client, Permissions, Token exchange, pick the Files API as target resource and tick files:access. The client needs the grant type token-exchange (RFC 8693). The tenant owner or a tenant administrator can set this. Then add the route of User tokens to your backend.

    Verify: exchanging a user’s token returns a token whose aud is files-api and whose scope is files:access. The answer is not unsupported_grant_type or invalid_target.

  7. Your web app’s origin is registered. (only when a browser calls the API)

    Add the origin of your web app, for example https://app.fitness.example, to allowed_origins of your application’s web (SPA) client in the admin UI. The service reads it from there, within about a minute. Nothing is configured on the service’s side. A browser that only PUTs to upload URLs and loads signed download URLs needs no registered origin.

    Verify: a browser call from your origin to GET P/settings/public passes the CORS check.

  8. Who may do what. (administrators)

    The tenant owner signs in to the Files console and opens Permissions. There the owner ticks, for each role, what it may do in the application, or in every application at once: view, download, edit, share, delete or approve everything, or change the settings and read the audit log. See Permissions page. A social app often maps nothing: its backend is the only writer and each member sees their own uploads and what the backend made visible.

    Verify: GET P/me/capabilities with that person’s token lists the keys, for example files.view.

  9. The application’s settings.

    Allowed types, the largest file, default visibility, what owners may do, approvals, share links and retention. Set them on the console’s Settings page or from code with files:config.manage. Every key is in the settings reference.

    Verify: GET P/settings/public answers your allowed types and size.

  10. Collect the values your code needs.

    See the table below.

Values you need

Section titled “Values you need”

Keep these in your configuration. The names are the suggested convention for your backend’s environment variables; the libraries read no variables themselves.

Value Convention Example or source
Issuer URL CCS_ISSUER_URL https://auth.centralcodestation.com, the bare origin with no /api
Backend client id and secret CCS_FILES_CLIENT_ID, CCS_FILES_CLIENT_SECRET From step 5 (and step 6: often the same client). Server-side only
Tenant id CCS_TENANT_ID The Identity Server tenant id
Application id CCS_APPLICATION_ID The id of your tenant application from step 2
Files API URL FILES_API_URL https://files.centralcodestation.com/api/v1
Files API resource identifier FILES_API_RESOURCE https://files.centralcodestation.com/api, sent as resource= in a token request

Your app needs none of these in the backend-mediated flow: it talks only to your API and to the signed URLs your API hands out.

Next steps

Section titled “Next steps”