Browser tokens

Browser tokens

Browser tokens allow you to query the SEEK API directly from a hirer’s browser or mobile app. This can reduce the complexity and overhead of mediating SEEK API access through your software’s backend.
A browser token is scoped to a SEEK hirer and a set of actions that can be performed on the hirer’s behalf. Their restricted scope makes them safe to send to authenticated users of your frontend.
Our GraphQL schema supports browser tokens for features that can be used interactively by hirers. A query or mutation’s schema documentation will indicate which scope it accepts. If browser tokens aren’t mentioned the operation will only accept partner tokens.

Request parameters

When requesting a browser token you provide three parameters along with your partner token:
  1. hirerId is the SEEK hirer associated with your frontend’s user. The returned browser token will only be able to access data related to the specified hirer.
  2. scope is a space-separated list of permitted scopes e.g. query:ad-products or query:ontologies query:ad-products. Each scope represents an action your frontend can perform with the returned browser token.
    Queries or mutations accepting browser tokens will indicate the required scope in their schema documentation . You can combine multiple scopes together to allow a browser token to be reused across different operations. However, including unnecessary scopes increases the security impact of a lost or compromised token.
  3. userId is a partner-specified identifier for the end user of your software.
    For effective tracking and debugging this should uniquely identify an end user. Do not include any personal information such as a legal name or email address. Instead, you can use an anonymous identifier such as a numeric ID or UUID assigned by your software.

Requesting a browser token

Exchange a partner token for a browser token using graphql.seek.com.
Partner frontendPartner backendauth.seek.comgraphql.seek.comRequest browser token1Authenticate frontend user2Send client credentials3Issue partner token4Send partner token and request parameters5Issue browser token6Return browser token7Make requests to the GraphQL endpoint8Partner frontendPartner backendauth.seek.comgraphql.seek.com
  1. Your frontend requests a browser token from your backend.
  2. Your backend authenticates its frontend user and finds the associated SEEK hirer.
  3. Your backend requests a partner token if one isn’t in cache.
  4. auth.seek.com issues your backend a partner token.
  5. Your backend calls the browser authentication endpoint with the partner token and the request parameters.
    Request
    Copy
    POST https://graphql.seek.com/auth/token HTTP/1.1
    Authorization: Bearer PARTNER_TOKEN_HERE
    Content-Type: application/json
    User-Agent: YourPartnerService/1.2.3
    {
      "hirerId": "seekAnzPublicTest:organization:seek:93WyyF1h",
      "scope": "query:ad-products query:ontologies",
      "userId": "317665"
    }
  6. graphql.seek.com validates your relationship with the SEEK hirer and issues your backend a browser token.
    Response
    Copy
    HTTP/1.1 200 OK
    Content-Type: application/json
    {
      "access_token": "BROWSER_TOKEN_HERE",
      "expires_in": 3600,
      "token_type": "Bearer"
    }
  7. Your backend returns the browser token to your frontend.
    Your frontend should cache the token for the number of seconds specified in the response’s expires_in. Alternatively, you can use an UNAUTHENTICATED error from the GraphQL endpoint to trigger a token refresh.
    Caching browser tokens is important for frontend performance as they can require multiple steps to refresh.
  8. Your frontend passes the browser token in the HTTP Authorization header when making requests to the GraphQL endpoint.
    Request
    Copy
    POST https://graphql.seek.com/graphql HTTP/1.1
    Authorization: Bearer PARTNER_TOKEN_HERE