{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml","oas-specs/authentication/device-code-access-token.yaml":"oas-specs/authentication/device-code-access-token.yaml","oas-specs/authentication/device-code-refresh-token.yaml":"oas-specs/authentication/device-code-refresh-token.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Device code authentication","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"device-code-authentication","__idx":0},"children":["Device code authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tyro Connect’s APIs require authentication, and Tyro Connect’s authorisation server uses the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://oauth.net/2/grant-types/device-code/"},"children":["OAuth 2.0 Device Code Flow"]}," to authenticate ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/getting-started/authentication"},"children":["POS Instance Connections"]},". App integrations don't use this flow — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/getting-started/authentication/client-credentials"},"children":["client credentials authentication"]}," instead."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To get started, you must first request a set of credentials from Tyro Connect, once provided these credentials will contain a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each request to a Tyro Connect API is authenticated with a JWT (JSON Web Token). Obtaining a JWT using the Device Code Flow is more complex than the Client Credentials Flow as the POS needs to provide a mechanism allowing the POS to be authorised to access Tyro Connect on behalf of the Merchant."]},{"$$mdtype":"Tag","name":"p","attributes":{"style":{"textAlign":"center"}},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/device-code-flow.b457af5d0e243e8066e3650b10cb3e532ae8b9ca45768b74f10c2b763059f7f7.e9401a08.png","alt":"Device Code Flow Diagram"},"children":[]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Best practice tips"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The credentials we provide you with are private and should be stored securely."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each JWT expires after 1 day. Partners are encouraged to monitor the expiry of their token and refresh expired tokens prior to making calls to any of the APIs."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-request-a-device-code","__idx":1},"children":["Step 1: Request a device code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The POS first makes a request to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://auth.connect.tyro.com/oauth/device/code"]}," endpoint of the authorisation server."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-specs/authentication/device-code-access-token.yaml","operationId":"generate-device-code","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification_uri"]},": This is the URL the user should visit to authorize the POS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_code"]},": The POS needs to prompt the user to enter this code into the form on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification_uri"]}," page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["interval"]},": Indicates the interval (in seconds) at which the POS should poll the token URL to request a token."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_code"]},": This parameter must be passed as part of the polling request, in the next step of authentication."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification_uri_complete"]},": This is the URL the user should visit to authorize the POS with the device code prepopulated for them. Use this URL if you can open it directly in a browser for the user to just log in."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-authorise-the-merchant","__idx":2},"children":["Step 2: Authorise the merchant"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The next step is to prompt the user to open a web browser, this can be on their mobile device or on the POS itself."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The user then needs to visit the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verification_uri"]}," that is part of the response in Step 1."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lastly the user needs to enter the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user_code"]}," onto the page."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-request-an-access-token","__idx":3},"children":["Step 3: Request an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["device_code"]}," from the response in Step 1 poll the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://auth.connect.tyro.com/oauth/token"]}," endpoint while waiting for the the user to complete Step 2."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-specs/authentication/device-code-access-token.yaml","operationId":"generate-token","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Authorisation server rate limits"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please respect the polling interval. The response from the call to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://auth.connect.tyro.com/oauth/device/code"]}," endpoint will contain an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["interval"]}," field."," ","Please make sure to wait this long between polling requests."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]},": This is the JWT token that you will use to make authenticated requests to Tyro Connect. You must pass the retrieved Access Token as a Bearer token in the Authorization header of your Tyro Connect REST API request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refresh_token"]},": This is the token that can be used to obtain a new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," after the previous one has expired. See Step 4 for more details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_type"]},": This value is always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]},": This is the number of seconds until the Access Token expires. Please use this value to determine when to request a new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," and to respect the rate limits of the authorisation server."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-refresh-an-access-token","__idx":4},"children":["Step 4: Refresh an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an access token expires rather than prompting the merchant every day to enter a code into a website it is much easier to programmatically generate a new Access Token using a Refresh Token."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This can be done by making a call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://auth.connect.tyro.com/oauth/token"]}," endpoint using the Refresh Token that is part of the response in Step 3:"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-specs/authentication/device-code-refresh-token.yaml","operationId":"refresh-token","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful response contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]},": This is the JWT token that you will use to make authenticated requests to Tyro Connect. You must pass the retrieved Access Token as a Bearer token in the Authorization header of your Tyro Connect REST API request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_type"]},": This value is always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]},": This is the number of seconds until the Access Token expires. The default value is 86400 seconds."]}]}]},"headings":[{"value":"Device code authentication","id":"device-code-authentication","depth":1},{"value":"Step 1: Request a device code","id":"step-1-request-a-device-code","depth":2},{"value":"Step 2: Authorise the merchant","id":"step-2-authorise-the-merchant","depth":2},{"value":"Step 3: Request an access token","id":"step-3-request-an-access-token","depth":2},{"value":"Step 4: Refresh an access token","id":"step-4-refresh-an-access-token","depth":2}],"frontmatter":{"seo":{"title":"Device code authentication"}},"lastModified":"2026-09-02T06:39:28.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/getting-started/authentication/device-code","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}