Authentication API

Overview

AirMap provides an API for authentication which allows users to login to AirMap and receive a token which is required to interact with certain APIs.

https://auth.airmap.com/realms/airmap/protocol/openid-connect/token

After obtaining a valid JSON Web Token (JWT) by querying the above endpoint, this access_token will have a TTL of 18000 seconds (5 hours) before it expires. To refresh (or generate a new valid token), you can query the same endpoint with params of grant_type=refresh_token&refresh_token=<refresh_token>.

Obtain Token

To get a valid JWT, you can post the https://auth.airmap.com/realms/airmap/protocol/openid-connect/token endpoint with the following parameters:

NameLocated inDescription
grant_typebodySet to password to authenticate using username/password or urn:ietf:params:oauth:grant-type:jwt-bearer to authenticate using an id_token
client_idbodyClient ID (found in Developer Portal application)
usernamebodyUsername of AirMap account (URL encoded)
passwordbodyPassword of AirMap account (URL encoded)
scopebodyLeave null to get only an access_token; Set to openid to also retrieve an id_token; Set to openid offline_access to also retrieve an id_token and refresh_token
devicebodyString value

๐Ÿšง

Note

It is recommended that the /openid-connect/token endpoint should only be queried once to obtain a refresh token for a specific user. After obtaining this refresh token, the application can use it to renew the id token and avoid having to store AirMap login credentials.

Example:

curl -X "POST" "https://auth.airmap.com/realms/airmap/protocol/openid-connect/token" \
    -d "grant_type=password" \
    -d "client_id={CLIENT ID}" \
    -d "username={USERNAME}" \
    -d "password={PASSWORD}"
var request = require('superagent');

request
  .post('https://auth.airmap.com/realms/airmap/protocol/openid-connect/token')
  .send({
      "grant_type": "password",
      "client_id": "{CLIENT_ID}",
      "username": "{USERNAME}",
      "password": "{PASSWORD}"
})
  .redirects(0)
  .end(function(err, res){
    if (err || !res.ok) {
      console.log(err);
    } else {
      console.log(JSON.stringify(res.body));
    }
  });
#!/usr/bin/env python3
"""AirMap authentication example"""

import requests

CLIENT_ID = "..."
USER_NAME = "..."
PASSWORD = "..."
URL = "https://auth.airmap.com/realms/airmap/protocol/openid-connect/token"
PAYLOAD = {
      'grant_type': 'password',
      'client_id': CLIENT_ID,
      'username': USER_NAME,
      'password': PASSWORD
}

resp = requests.post(URL, data=PAYLOAD)
print(resp.status_code)
TOKEN = resp.json()["access_token"]
print(TOKEN)
require 'net/http'
require 'net/https'
require 'json'

def send_request
  begin
    uri = URI("https://auth.airmap.com/realms/airmap/protocol/openid-connect/token")

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
    
    dict = {
          "grant_type" => "password",
          "client_id" => "{CLIENT ID}",
          "username" => "{USERNAME}",
          "password" => "{PASSWORD}"
        }
    body = JSON.dump(dict)

    # Create Request
    req =  Net::HTTP::Delete.new(uri)
    req.body = body

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

The response contains the valid JWT:

{'access_token': 'eyJhbGciO...',
 'expires_in': 18000,
 'not-before-policy': 0,
 'refresh_expires_in': 18000,
 'refresh_token': 'eyJhbGciO...',
 'scope': 'sfo email am-api',
 'session_state': '5668336b-...',
 'token_type': 'bearer'
}

Refresh Token

To refresh your token by generating a new token, you can post the https://auth.airmap.com/realms/airmap/protocol/openid-connect/token endpoint with the following parameters:

grant_typebodySet to password to authenticate using username/password or urn:ietf:params:oauth:grant-type:jwt-bearer to authenticate using an id_token
client_idbodyClient ID (found in Developer Portal application)
id_token or refresh_tokenbodyThe existing token of the user

Example:

curl -X "POST" "https://auth.airmap.com/realms/airmap/protocol/openid-connect/token" \
    -d "grant_type=refresh_token" \
    -d "client_id={CLIENT ID}" \
    -d "refresh_token={REFRESH TOKEN}"
var request = require('superagent');

request
  .post('https://auth.airmap.com/realms/airmap/protocol/openid-connect/token')
  .send({
      "grant_type": "refresh_token",
      "client_id": "{CLIENT_ID}",
      "refresh_token": "{REFRESH TOKEN}"
})
  .redirects(0)
  .end(function(err, res){
    if (err || !res.ok) {
      console.log(err);
    } else {
      console.log(JSON.stringify(res.body));
    }
  });
import requests

CLIENT_ID = "..."
REFRESH_TOKEN = "..."
DEVICE = "..."
URL = "https://auth.airmap.com/realms/airmap/protocol/openid-connect/token"
PAYLOAD = {
      'grant_type': 'refresh_token',
      'client_id': CLIENT_ID,
      'refresh_token': REFRESH_TOKEN
}

resp = requests.post(URL, data=PAYLOAD,)
print(resp.status_code)
TOKEN = R.json()["id_token"]
print(TOKEN)
require 'net/http'
require 'net/https'
require 'json'

def send_request
  begin
    uri = URI('https://auth.airmap.com/realms/airmap/protocol/openid-connect/token')

    # Create client
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_PEER
    
    dict = {
          "grant_type" => "refresh_token",
          "client_id" => "{CLIENT ID}",
      "refresh_token" => "{REFRESH TOKEN}"
        }
    body = JSON.dump(dict)

    # Create Request
    req =  Net::HTTP::Delete.new(uri)
    req.body = body

    # Fetch Request
    res = http.request(req)
    puts "Response HTTP Status Code: #{res.code}"
    puts "Response HTTP Response Body: #{res.body}"
  rescue StandardError => e
    puts "HTTP Request failed (#{e.message})"
  end
end

The response contains the valid JWT:

{
  'access_token': 'eyJhbGciO...', 
  'expires_in': 18000, 
  'refresh_expires_in': 18000, 
  'refresh_token': 'eyJhbGciO...', 
  'token_type': 'bearer', 
  'not-before-policy': 0, 
  'session_state': '7c944804-...', 
  'scope': 'sfo email am-api'
}

Updated 4 months ago

Authentication API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.