1. /Authentication
  2. /Device Authorization Flow With PKCE

Device Authorization Flow With PKCE

This section describes how to implement the Device Authorization Flow with Navigraph API. For general information about this type of authentication, see RFC 8628 - OAuth 2.0 Device Authorization Grant.

This is the recommended flow to use for desktop applications and in-process applications such as flight simulator add-ons. It is lightweight and does not have external dependencies on system browsers and callbacks. Works in any environment that can fetch data using https, including Microsoft Flight Simulator. Ideal for deployment to multiple targets including consoles and other keyboard-less devices.

For web and mobile applications it might be more convenient to use the Authorization Code flow.

OverviewRead the “Overview” section

  1. The user initiates the authentication.

  2. The application requests authorization from the Navigraph Identity Server using its Client ID and Client Secret.

  3. The Navigraph Identity Server responds with a device_codeuser_codeverification_uriverification_uri_complete expires_in (lifetime in seconds for device_code and user_code), and polling interval.

  4. The application asks the user to authorize the app. The application needs to provide atleast one of the following methods:

    • in environments that has access to the default browser, navigate to verification_uri_complete
    • asking the user to interact with a QR Code generated from the verification_uri_complete
    • display the user_code on-screen and ask the user to visit the verification_uri to enter the code manually
  5. The application begins polling the Navigraph Identity Server for an Access Token) using the time period specified by interval. The application continues polling until either the user completes authentication flow or the user code expires.

  6. The user authenticates using one of the configured login options (4) and may see a consent page listing the requested permissions.

  7. When the user successfully completes the authentication flow, the Navigraph Identity Server responds with an Access Token and a Refresh Token.

  8. The application can now use the Access Token to access the Navigraph API and the Refresh Token to get new tokens periodcially.

AuthenticationRead the “Authentication” section

The client initiates the Device Authorization Flow by requesting a set of verification codes from the authorization server by issuing an HTTP POST request to the device authorization endpoint. The following parameters should be included by using the application/x-www-form-urlencoded format, with a character encoding of UTF-8 in the HTTP request entity-body:

POST /connect/deviceauthorization HTTP/1.1
Content-Type: application/x-www-form-urlencoded


Parameters for /connect/deviceauthorizationRead the “Parameters for /connect/deviceauthorization” section

client_idThe Client IDThe client_id is the id for your client which you will obtain from Navigraph.
client_secretThe Client SecretThe client_secret is the secret password for your client which you will obtain from Navigraph.
code_challenge43 character code challengePKCE code_challenge read more about how to generate it here.
code_challenge_method"S256"PKCE code_challenge_method should be set to S256 for SHA256.

Successful deviceauthorization responseRead the “Successful deviceauthorization response” section

On successful response the following JSON structure is returned:

  "device_code": "kGUXxCuykgN0MV4PrsyARH360sfGrPZ8",
  "verification_uri": "",
  "verification_uri_complete": "",
  "user_code": "THRGZFC6",
  "expires_in": 1800,
  "interval": 5

(On errors the authorization server responds in the same way as the token endpoint specified in Section 5.2 of [RFC6749].)

Your application should now instruct the user to use a browser to navigate to the uri given in verification_uri. As a quicker way of authenticating you are recommended to also convert the verification_uri_complete into a QR-code and display for the user who could directly authenticate using a mobile device.

The user will be asked by our servers to give consent for your application to approve or deny the request to authorize your application. Once this process is complete the user will be instructed to return to your application.

At the same time as you wait for the user to authorize the application you need to start a polling-scheme to be able to react on the authorization that the user is performing on our server. You do this by issuing periodical HTTP POST requests to our token-endpoint, with the interval given from the /connect/deviceauthorization endpoint in seconds:

POST /connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=kGUXxCuykgN0MV4PrsyARH360sfGrPZ3JNA&code_verifier=<code_verifer>&client_id=<client-id>&client_secret=<client-secret>&scope=openid charts offline_access

Parameters for /connect/tokenRead the “Parameters for /connect/token” section

grant_typeurn:ietf:params:oauth:grant-type:device_codeShould always be "urn:ietf:params:oauth:grant-type:device_code"
device_codeThe Device CodeThis is the device_code which you receieved from the /connect/deviceauthorization endpoint.
client_idThe Client IDThe client_id is the id for your client which you will obtain from Navigraph.
client_secretThe Client SecretThe client_secret is the secret password for your client which you will obtain from Navigraph.
scope"openid offline_access"Scopes enable your application to access specific API endpoints on behalf of a user. The set of scopes you pass in your call determines the access permissions that the user is required to grant. For FMS Data add "fmsdata" and for charts add "charts".
code_verifier43 character Code VerifierPKCE code_verifier, read about how to generate it here.

Error responsesRead the “Error responses” section

These are the errors that you can expect from the /connect/token endpoint

ErrorDescriptionHttp Code
authorization_pendingThe user has not yet approved/denied your request on our servers. You should therefore repeat the request again after the interval you got from the /connect/deviceauthorization endpoint.400
slow_downThis is basically the same as authorization_pending, but you have been polling too quickly. The interval MUST be increased by 5 seconds for this and all subsequent requests.400
access_deniedThe authorization request was denied by the user. Stop the polling and adjust UI in your application as needed.400
expired_tokenThe "device_code" has expired, and the device authorization session has concluded. You should provide an error message and let your user initiate the flow again.400

Successful token responseRead the “Successful token response” section

  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjA0X3JsNjNvV2ZBSVc3WEd4UWUzQzVEY3dkTSIsImtpZCI6IjA0X3JsNjNvV2ZBSVc3WEd4UWUzQzVEY3dkTSJ9.eyJpc3MiOiJodHRwczovL2lkZW50aXR5LmFwaS5uYXZpZ3JhcGguY29tIiwiYXVkIjoiaHR0cHM6Ly9pZGVudGl0eS5hcGkubmF2aWdyYXBoLmNvbS9yZXNvdXJjZXMiLCJleHAiOjE2MTE1MTA2MjQsIm5iZiI6MTYxMTUwNzAyNCwiY2xpZW50X2lkIjoiZmJ3LWEzMm54Iiwic2NvcGUiOlsiY2hhcnRzIiwiZm1zZGF0YSIsIm9mZmxpbmVfYWNjZXNzIiwib3BlbmlkIl0sInN1YiI6ImM3YTIwY2JlLTU4ZjQtNDA3ZS1hZjJmLTVjODRmMTE5YzJlNiIsImF1dGhfdGltZSI6MTYxMTUwNzAyNCwiaWRwIjoiaWRzcnYiLCJ1cGRhdGVkX2F0IjoxNjA3MDgzNDI0LCJ0ZW5hbnQiOiJkZWZhdWx0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibTRya3VzIiwiZW1haWwiOiJtYXJrdXNAZ3JhbmRub2lzZS5zZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJnaXZlbl9uYW1lIjoiTWFya3VzIiwiZmFtaWx5X25hbWUiOiJIYW1idXJnZXIiLCJwbGF5X3JvbGUiOiJ1c2VyIiwiYmV0YSI6InRydWUiLCJsb2ciOiJkZWJ1ZyIsImVtYWlsX2JvdW5jZWQiOiIwIiwiZW1haWxfbWFuYWdlX2tleSI6IjA0MjBGMURGLUU0MzMtNEFBMC1BRjBBLTBDNTg3QzU4MTZEQSIsInJvbGUiOiJhZG1pbiIsInRvcyI6IkZhbHNlIiwiZW1haWxfc2V0dGluZyI6IjAiLCJuYW1lIjoibTRya3VzIiwiYW1yIjpbInVybjppZXRmOnBhcmFtczpvYXV0aDpncmFudC10eXBlOmRldmljZV9jb2RlIl0sImFkZHJlc3MiOnsiY291bnRyeSI6IlNFIn19.nbG-Lu_87Z0nSVuPByrBowfX7rRLuHEVKHH7vjIpISBtm4Hh4pF4zjuTgL9xrRb70cPxcKoqEsY48lur-vED34bAspZda4tuLzH9NYHlF7FSgPVxxXpVP65KOG1wJwsSjFEsVkQzq8N6GeM0iqbevpZM-lXHijgAqgINJ-X4_P5YHbryMKVlWJv8mBNgUU3TQ0RHcChCEcRnAgRne0noxskSv3FD__UUmhAQxWyTMW7rFd0jIkB5pIEw5uIyZEz-uXReshDiZgA1_knSYb36XrnpYT0kRoao92Jw6MfLrtL8CV33W-G4aYZjBJRrIvstTSyukF7s0oh5gmhCibYQvA",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "399045b904e1d5b515c2d3de5a1fcd7c"

Congratulations! You have now finished the device-flow. The following header should be added to all further requests to our API endpoints using the access-token you just recieved:

Authorization: Bearer <access_token>

Refreshing tokensRead the “Refreshing tokens” section

Without a valid access-token our servers will respond to your requests with HTTP 401 UNAUTHORIZED. The access-token has a limited lifetime of about 60 minutes. When it expires you need to fetch a new token. You do this with a simple call to our token-endpoint where you provide the refresh-token in return for a new access-token and a new refresh-token. The refresh-token can only be used once, so be sure to not only update your access-token but also your refresh-token for every refresh.

POST /connect/token/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded


Notice that the refresh-token is long-lived, it is therefore recommended to use it the next time your user starts your application to retrieve tokens to avoid having the user manually login using the device flow again.