Browser tokens

    Suggestions will appear below the field as you type

    Browser tokens

      Suggestions will appear below the field as you type

      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 object identifier associated with your frontend’s user. The returned browser token will only be able to access data related to the specified hirer.
        To support migration from the Job Posting API, stringified SEEK advertiser IDs are also accepted. Your software should switch to hirer object identifiers before completing your migration to the SEEK API.
      2. scope is a space-separated list of permitted scopes e.g. query:ontologies or query:ad-products query:organizations. 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.
      1. Your frontend requests a browser token from your backend.
        If a user switches to a different SEEK hirer account in your software, your software should request a token for the new hirer ID.
      2. Your backend authenticates and authorises the user.
        Your software is responsible for verifying that the user is authorised to access a given hirer ID. A user must not be able to request a browser token for an arbitrary organization that they do not belong to.
      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 query:organizations",
          "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 must cache the token for the number of seconds specified in the response’s expires_in. The cache expiry must be read from each response; it cannot be hardcoded as the token lifetime is dynamic and may be updated without notice. Alternatively, you can use an UNAUTHENTICATED error from the GraphQL endpoint to trigger a new token request. Caching browser tokens is important for frontend performance as requesting a new token can require multiple steps.
      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 BROWSER_TOKEN_HERE

      Token expiration

      Re-initiate the token exchange flow in the above section to obtain a new browser token. Note that this flow does not feature a refresh token.
      Using a browser token right up to its expiry may lead to expiration occurring mid-flight due to clock drift or request latency. Consider leaving a reasonable buffer of around a minute, or obtaining a new browser token and retrying the request on an UNAUTHENTICATED error.

      Introspecting browser tokens

      You can use the self query  to return the associated SEEK hirer for a browser token. This requires that the token includes the query:organizations scope. If the token has expired the query will fail with an UNAUTHENTICATED error.
      QueryResult
      CopyGraphQL Explorer
      query {
        self {
          hirer {
            id {
              value
            }
            name
          }
        }
      }
      Auth: Partner tokens
      Auth: Hirer relationships