Security for Crowdin Apps

When you build a self-hosted app that works with data from Crowdin, it authenticates with crowdin_app and receives a signed JWT token with every request Crowdin sends it. Verifying that token is how the app tells a real request from anything else.

Both SDKs handle this for you: the Crowdin Apps SDK validates the token and extracts the context, and a serverless app never receives a token at all. What follows is for apps that verify requests themselves, for example one written in another language.

Nota

Apps with the Workflow Step Type module use the crowdin_agent authentication type instead of crowdin_app.

What Crowdin Sends

Crowdin opens a module page with the token and its context in the query string:

https://example.com/app-module?jwtToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJCcjRhMmhwUW……MX0.yt-lbv3Z8JyIGX4jG405mjZvX8lwc1q0EfWdTtm9GCc&origin=https://{domain}.crowdin.com&clientId=your-client-id

Query parameters:

jwtToken	Type: string Description: JWT token used for authorization.
origin	Type: string (url) Description: Host used for opening a module page.
clientId	Type: string Description: The ID of the OAuth Client used for authorization.

The token is signed with the OAuth Client Secret, which only Crowdin and your app know, so a valid signature is proof of where the request came from. Verify the signature and the expiry of every token your app receives, for example in a middleware that runs before the rest of your code. Any of the existing libraries does it for you.

Token Payload

{
  "aud": "Br4a2hpQiNW96anuuO4a",
  "sub": "1",
  "domain": null,
  "context": {},
  "iat": 1600000000,
  "exp": 1600000900
}

Properties:

aud	Type: string Description: ID of the OAuth Client that issued the token.
sub	Type: string Description: Identifier of the user that is making a request to the Crowdin app.
domain	Type: string|null Description: The organization the app is accessed from. Always present, and always null in Crowdin.
context	Type: object Description: The environment where the module is opened, such as the project, the locale, and the user’s timezone.
iat	Type: integer Description: Identifies the issue time of the token.
exp	Type: integer Description: Identifies the expiration time of the token.