API Request Verification

Verify requests to your API(s) using Gobo access tokens.

Access tokens are issued by Gobo to allow your partners' apps to access one or many of your API(s). Gobo access tokens conform to the JSON Web Token (JWT) standard and contain information in the form of claims. They are self-contained, therefore it is not necessary for the recipient to call a server to validate the token.

Once a customeruser installs an app into a customerorg, an app can request an access token from Gobo and begin making calls to your API(s).

Example Access Tokens

Token issued using the OAuth 2.0 client credentials flow:

App Access Token

  {
    "ver": "1.2",
    "iss": "https://yourco.withgobo.com",
    "sub": "ac4811a2-339e-4a34-b65b-dafe1c0a7f9c",  // app client_id
    "aud": [
      "https://yourapi1.yourco.com",                // proxy origins
      "https://yourapi2.yourco.com"
    ],
    "azp": "ac4811a2-339e-4a34-b65b-dafe1c0a7f9c",  // app client_id
    "exp": 1704067199,
    "iat": 1685124578,
    "scope": "foo bar",
    "install": "f13542ae-119e-4d81-935c-e93c1ee6b097",
    "app": "ac4811a2-339e-4a34-b65b-dafe1c0a7f9c",
    "app_type": "oauth",
    "org": "7a9923a7-cebb-4521-b3d0-bb4101351fcd",
    "org_id": "ABC",
    "token": "go_wwPYYUcGhngr2SdTCTa9rvIOR3O87n5gRKHln5H5iF2Pg2lkJ4weE2vhy02"
  }

Token issued using the OAuth 2.0 authorization code flow:

User Access Token

  {
    "ver": "1.2",
    "iss": "https://marketplace.yourco.com",
    "sub": "ac4811a2-339e-4a34-b65b-dafe1c0a7f9c",  // customeruser guid
    "aud": [
      "https://yourapi.yourco.com"                  // proxy origin
    ],
    "azp": "ac4811a2-339e-4a34-b65b-dafe1c0a7f9c",  // app client_id
    "exp": 1704067199,
    "iat": 1685124578,
    "scope": "foo bar",
    "install": "f13542ae-119e-4d81-935c-e93c1ee6b097",
    "app": "ac4811a2-339e-4a34-b65b-dafe1c0a7f9c",
    "app_type": "oauth",
    "org": "7a9923a7-cebb-4521-b3d0-bb4101351fcd",
    "org_id": "ABC",
    "user": "8217ac57-31c1-4b8a-965b-79fec333811c",
    "user_id": "123",
    "token": "go_qwPYYUcGhegrZSdTCsa9rvIORQO8Gn5gRKHln5H3is2Pg2lkJ4weEjvhy07"
  }

Verifying Access Tokens

Gobo JWT access tokens are signed using HS256 (HMAC with SHA-256), a symmetric key hashing algorithm that uses a shared secret. By using the Gobo signing key provided in the Gobo Dashboard, you are able to verify that the access token was generated by Gobo and has not been modified.

There are JWT libraries available for most languages that automate the process of decoding and verification:

Node.js Example

const jwt = require("jsonwebtoken");

const GOBO_SIGNING_KEY = "gk_...";

function authenticateToken(req, res, next) {
  const authHeader = req.headers["authorization"];
  const token = authHeader && authHeader.split(" ")[1];
  if (token == null) return res.sendStatus(403);

  jwt.verify(token, GOBO_SIGNING_KEY, (err, payload) => {
    if (err) {
        console.error(err);
        return res.sendStatus(401);
    }
    
    req.org = payload.org_id;
    req.user = payload.user_id;
    next();
  })
}

For additional security, you can ensure that the access token was generated for API receiving the request by verifying the aud claim against the associated Gobo API GUID.

Keep your Signing Key Secure

The tenant signing key ensures that your access tokens were generated by Gobo and have not been modified. It must be kept secure and private. Be sure to prevent your signing key from being made publicly accessible, such as in client-side code, GitHub, unsecured S3 buckets, and so forth. API Tokens are prefixed with gk_.