Authentication

via API Key

post

To authenticate to the API, a JWT request token is encoded and sent as the jwt param in a POST to /auth/token. The access_token in the response is the JWT bearer token that is included as the Authorization value in the Header of all subsequent API calls.

If you do not have a NETOSECRET API key, see Create a Netography API Key. The NETOSECRET string is a base64 encoded JSON string that contains the secrets needed to construct a JWT request token. It is NOT a JWT request token itself -- you must generate it from that value.

Generating a JWT request token in code

Create a JWT Request Token.

To authenticate to the API on this page, you need to copy the token string from the JWT Request Token field directly above, and paste it into the jwt field directly below.

Body

application/json

jwtstringRequired

A JWT token encoded using your Accounts API Key Shared Secret.

Example: asd8asd9f87ass...asdf9

Responses

200

A JSON object which contains the access_token to use in all subsequent calls to the API

application/json

access_tokenstringRead-onlyOptional

Access Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

expires_inintegerRead-onlyOptional

Seconds until the Access Token expires

Example: 86400

refresh_expires_inintegerRead-onlyOptional

Seconds until the Refresh Token expires

Example: 86400

refresh_tokenstringRead-onlyOptional

Refresh Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

token_typestringRead-onlyOptional

Type of JWT token. Will always be "bearer"

Example: bearer

id_tokenstringRead-onlyOptional

ID Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

not-before-policyintegerRead-onlyOptional

Seconds until the Token will be considered valid. Will always be 0 (now).

Example: 0

session-statestringRead-onlyOptional

Unique Session ID

Example: 9b4b13d7-c7a6-4f68-a419-cf1bf5aef94f

scopestringRead-onlyOptional

Application Scopes

Example: openid email app_metadata user_metadata profile

401

Missing or invalid credentials

application/json

404

Not Found

application/json

default

Unknown Error Occurred

application/json

post

/api/v1/auth/token

HTTPcURLJavaScriptPython

POST /api/v1/auth/token HTTP/1.1
Host: api.netography.com
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "jwt": "asd8asd9f87ass...asdf9"
}

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "expires_in": 86400,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "token_type": "bearer",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "not-before-policy": 0,
  "session-state": "9b4b13d7-c7a6-4f68-a419-cf1bf5aef94f",
  "scope": "openid email app_metadata user_metadata profile"
}

via User Credentials

post

Obtain an access_token via User Credentials

Body

application/x-www-form-urlencoded

usernamestringRequiredExample: [email protected]

passwordstring · passwordRequired

Responses

200

A JSON object which contains the access_token to use in all subsequent calls to the API

application/json

access_tokenstringRead-onlyOptional

Access Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

expires_inintegerRead-onlyOptional

Seconds until the Access Token expires

Example: 86400

refresh_expires_inintegerRead-onlyOptional

Seconds until the Refresh Token expires

Example: 86400

refresh_tokenstringRead-onlyOptional

Refresh Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

token_typestringRead-onlyOptional

Type of JWT token. Will always be "bearer"

Example: bearer

id_tokenstringRead-onlyOptional

ID Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

not-before-policyintegerRead-onlyOptional

Seconds until the Token will be considered valid. Will always be 0 (now).

Example: 0

session-statestringRead-onlyOptional

Unique Session ID

Example: 9b4b13d7-c7a6-4f68-a419-cf1bf5aef94f

scopestringRead-onlyOptional

Application Scopes

Example: openid email app_metadata user_metadata profile

401

Missing or invalid credentials

application/json

default

Unknown Error Occurred

application/json

post

/api/auth/bearer/token

HTTPcURLJavaScriptPython

POST /api/auth/bearer/token HTTP/1.1
Host: api.netography.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 49

"username='[email protected]'&password='password'"

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "expires_in": 86400,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "token_type": "bearer",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "not-before-policy": 0,
  "session-state": "9b4b13d7-c7a6-4f68-a419-cf1bf5aef94f",
  "scope": "openid email app_metadata user_metadata profile"
}

via Refresh Token

post

Obtain a new access_token via a refresh_token

Body

application/x-www-form-urlencoded

refresh_tokenstringRequiredExample: eyJhbGciOiJIUzI1NiIsInR5c...jUZ8Ud9wGCYilcqEML2fRkWZU

Responses

200

A JSON object which contains the access_token to use in all subsequent calls to the API

application/json

access_tokenstringRead-onlyOptional

Access Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

expires_inintegerRead-onlyOptional

Seconds until the Access Token expires

Example: 86400

refresh_expires_inintegerRead-onlyOptional

Seconds until the Refresh Token expires

Example: 86400

refresh_tokenstringRead-onlyOptional

Refresh Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

token_typestringRead-onlyOptional

Type of JWT token. Will always be "bearer"

Example: bearer

id_tokenstringRead-onlyOptional

ID Token (JWT)

Example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM

not-before-policyintegerRead-onlyOptional

Seconds until the Token will be considered valid. Will always be 0 (now).

Example: 0

session-statestringRead-onlyOptional

Unique Session ID

Example: 9b4b13d7-c7a6-4f68-a419-cf1bf5aef94f

scopestringRead-onlyOptional

Application Scopes

Example: openid email app_metadata user_metadata profile

400

Wrong or expired refresh token, or user/api-key removed

application/json

default

Unknown Error Occurred

application/json

post

/api/auth/bearer/refresh

HTTPcURLJavaScriptPython

POST /api/auth/bearer/refresh HTTP/1.1
Host: api.netography.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 73

"refresh_token='eyJhbGciOiJIUzI1NiIsInR5c...jUZ8Ud9wGCYilcqEML2fRkWZU'"

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "expires_in": 86400,
  "refresh_expires_in": 86400,
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "token_type": "bearer",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI....KpQXk3fiwnSbREHlvfdi7weWuM",
  "not-before-policy": 0,
  "session-state": "9b4b13d7-c7a6-4f68-a419-cf1bf5aef94f",
  "scope": "openid email app_metadata user_metadata profile"
}