NMOS Authorization API documentation
https://api.example.com
Overview
The NMOS Authorization API is exposed by an Authorization Server as a standard interface for requesting, revoking, and managing tokens and client registration.
Authorization Servers may use alternative paths for the required endpoints, provided these are reflected in the Authorization Server Metadata. The endpoints may share a common base path that is the path component of the issuer identifier or api_selector, for example 'x-nmos/auth/{api version}', but this is not mandatory.
Endpoint Discovery
The Authorization Server URL is discoverable using unicast and/or multicast DNS using the '_nmos-auth._tcp' service name.
Use of HTTPS/TLS
The Authorization Server MUST require the use of TLS when interacting with the token and authorization endpoints.
OAuth 2.0 Dynamic Client Registration endpoint
Resource for registering clients with the authorization server. See RFC 7591.
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
post /{registration_endpoint_path}
Resource for registering clients with the authorization server. See RFC 7591.
URI Parameters
- registration_endpoint_path: required(string)
This path is defined by the registration_endpoint in the OAuth 2.0 Authorization Server Metadata, as per RFC 8414 Section 2.
Example:
register
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Register Client Request",
"description": "Object defining client registration request",
"type": "object",
"properties": {
"redirect_uris": {
"description": "Array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows",
"type": "array",
"items": {
"type": "string"
}
},
"token_endpoint_auth_method": {
"description": "String indicator of the requested authentication method for the token endpoint",
"type": "string"
},
"grant_types": {
"description": "Array of OAuth 2.0 grant type strings that the client can use at the token endpoint",
"type": "array",
"items": {
"type": "string"
}
},
"response_types": {
"description": "Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint",
"type": "array",
"items": {
"type": "string"
}
},
"client_name": {
"description": "Human-readable string name of the client to be presented to the end-user during authorization",
"type": "string"
},
"client_uri": {
"description": "URL string of a web page providing information about the client",
"type": "string"
},
"logo_uri": {
"description": "URL string that references a logo for the client",
"type": "string"
},
"scope": {
"description": "String containing a space-separated list of scope values",
"type": "string"
},
"contacts": {
"description": "Array of strings representing ways to contact people responsible for this client, typically email addresses",
"type": "array",
"items": {
"type": "string"
}
},
"tos_uri": {
"description": "URL string that points to a human-readable terms of service document for the client",
"type": "string"
},
"policy_uri": {
"description": "URL string that points to a human-readable privacy policy document",
"type": "string"
},
"jwks_uri": {
"description": "URL string referencing the client's JSON Web Key (JWK) Set document, which contains the client's public keys",
"type": "string"
},
"jwks": {
"description": "Client's JSON Web Key Set document value, which contains the client's public keys",
"type": "object",
"allOf": [
{"$ref": "jwks_schema.json"}
]
},
"software_id": {
"description": "A unique identifier string (e.g. a UUID) assigned by the client developer or software publisher",
"type": "string"
},
"software_version": {
"description": "A version identifier string for the client software identified by 'software_id'",
"type": "string"
}
},
"required": [ "client_name" ]
}
Examples:
AuthCodeGrant:
{
"client_name": "My Example Client",
"grant_types": ["authorization_code", "refresh_token"],
"redirect_uris": [
"https://client.example.com/callback",
"https://client.example.com/callback2"
],
"response_types": ["code"],
"scope": "query connection",
"token_endpoint_auth_method": "client_secret_basic"
}
ClientCredentialsGrant:
{
"client_name": "My Example Client",
"grant_types": ["client_credentials"],
"jwks_uri": "https://client.example.com/my_public_keys.jwks",
"response_types": ["none"],
"scope": "registration",
"token_endpoint_auth_method": "private_key_jwt"
}
HTTP status code 201
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Register Client Response",
"description": "Object defining successful client registration",
"type": "object",
"properties": {
"client_id": {
"description": "OAuth 2.0 client identifier string",
"type": "string"
},
"client_secret": {
"description": "OAuth 2.0 client secret string",
"type": "string"
},
"client_id_issued_at": {
"description": "UTC time at which the client identifier was issued",
"type": "number"
},
"client_secret_expires_at": {
"description": "Time at which the client secret will expire or 0 if it will not expire",
"type": "number"
},
"redirect_uris": {
"description": "Array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows",
"type": "array",
"items": {
"type": "string"
}
},
"token_endpoint_auth_method": {
"description": "String indicator of the requested authentication method for the token endpoint",
"type": "string",
"default": "client_secret_basic"
},
"grant_types": {
"description": "Array of OAuth 2.0 grant type strings that the client can use at the token endpoint",
"type": "array",
"items": {
"type": "string"
},
"default": [ "authorization_code" ]
},
"response_types": {
"description": "Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint",
"type": "array",
"items": {
"type": "string"
},
"default": [ "code" ]
},
"client_name": {
"description": "Human-readable string name of the client to be presented to the end-user during authorization",
"type": "string"
},
"client_uri": {
"description": "URL string of a web page providing information about the client",
"type": "string"
},
"logo_uri": {
"description": "URL string that references a logo for the client",
"type": "string"
},
"scope": {
"description": "String containing a space-separated list of scope values",
"type": "string"
},
"contacts": {
"description": "Array of strings representing ways to contact people responsible for this client, typically email addresses",
"type": "array",
"items": {
"type": "string"
}
},
"tos_uri": {
"description": "URL string that points to a human-readable terms of service document for the client",
"type": "string"
},
"policy_uri": {
"description": "URL string that points to a human-readable privacy policy document",
"type": "string"
},
"jwks_uri": {
"description": "URL string referencing the client's JSON Web Key (JWK) Set document, which contains the client's public keys",
"type": "string"
},
"jwks": {
"description": "Client's JSON Web Key Set document value, which contains the client's public keys",
"type": "object",
"allOf": [
{"$ref": "jwks_schema.json"}
]
},
"software_id": {
"description": "A unique identifier string (e.g. a UUID) assigned by the client developer or software publisher",
"type": "string"
},
"software_version": {
"description": "A version identifier string for the client software identified by 'software_id'",
"type": "string"
}
},
"required": ["client_id"]
}
Examples:
AuthCodeGrant:
{
"client_id": "s6BhdRkqt3",
"client_id_issued_at": 2893256800,
"client_secret": "cf136dc3c1fc93f31185e5885805d",
"client_secret_expires_at": 2893276800,
"redirect_uris": [
"https://client.example.com/callback",
"https://client.example.com/callback2"
],
"scope": "query connection",
"token_endpoint_auth_method": "client_secret_basic"
}
ClientCredentialsGrant:
{
"client_id": "s6BhdRkqt3",
"client_id_issued_at": 2893256800,
"client_name":"My Example Client",
"grant_types":["client_credentials"],
"jwks_uri":"https://client.example.com/my_public_keys.jwks",
"scope": "registration",
"token_endpoint_auth_method":"private_key_jwt"
}
HTTP status code 400
Unsuccessful client registration (in line with Section 3.2.2. of RFC 7591)
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Client Registration Error Response",
"description": "Describes the client registration endpoint's OAuth error response",
"type": "object",
"minItems": 1,
"properties": {
"error": {
"description": "Error Type",
"type": "string",
"enum": ["invalid_redirect_uri", "invalid_client_metadata", "invalid_software_statement", "unapproved_software_statement"]
},
"error_description": {
"description": "Human-readable ASCII text providing additional information",
"type": "string"
},
"error_uri": {
"description": "A URI identifying a human-readable web page with information about the error",
"type": "string",
"format": "uri"
}
},
"required": ["error"]
}
Example:
{
"error": "invalid_redirect_uri"
}
options /{registration_endpoint_path}
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
OAuth 2.0 Token endpoint
Method for requesting OAuth 2.0 Bearer Token (Authorization Code, Client Credentials and Refresh Token grants).
Note: The data flow is dependent on the chosen grant type (e.g. authorization_code, refresh_token, etc.)
Note: Request examples may be rendered as JSON objects, but should be passed in as "application/x-www-form-urlencoded" MIME type, in accordance with RFC 6749.
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
post /{token_endpoint_path}
Method for requesting OAuth 2.0 Bearer Token (Authorization Code, Client Credentials and Refresh Token grants).
Note: The data flow is dependent on the chosen grant type (e.g. authorization_code, refresh_token, etc.)
Note: Request examples may be rendered as JSON objects, but should be passed in as "application/x-www-form-urlencoded" MIME type, in accordance with RFC 6749.
This API supports Basic Authentication using client ID and client secret as username and password credentials respectively.
This API supports authentication using a JSON Web Token, signed by a private key which the Authorization Server holds the corresponding public key for.
URI Parameters
- token_endpoint_path: required(string)
This path is defined by the token_endpoint in the OAuth 2.0 Authorization Server Metadata, as per RFC 8414 Section 2.
Example:
token
Headers
- Authorization: required(string)
Colon-seperated, base-64 encoded string, of Client ID and Client Secret
Body
Media type: application/x-www-form-urlencoded
Type: TokenAuthorizeRequest | TokenCredentialsRequest | TokenRefreshRequest
Examples:
AuthCodeGrant:
{
"grant_type": "authorization_code",
"code": "SplxlOBeZQQYbYS6WxSbIA",
"redirect_uri": "http://client.example.com/",
"client_id": "ttwCD9hb4OckmcGDnmC3J3Jr"
}ClientCredentialsGrant:
{
"grant_type": "client_credentials",
"client_id": "c1068569-80c1-48cf-982e-30c3f930dfe3",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI...."
}RefreshTokenGrant:
{
"grant_type": "refresh_token",
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}HTTP status code 200
Successful request to obtain a Bearer Token, consisting of the Access Token and optionally a Refresh Token to be used to request further Access Tokens.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Token Response",
"description": "OAuth2 Response for the request of a Bearer Token",
"type": "object",
"properties": {
"access_token": {
"description": "Access Token to be used in accessing protected endpoints",
"type": "string"
},
"expires_in": {
"description": "The lifetime in seconds of the Access Token",
"type": "integer"
},
"refresh_token": {
"description": "Refresh Token to be used to obtain further Access Tokens",
"type": "string"
},
"scope": {
"description": "The scope of the Access Token",
"type": "string"
},
"token_type": {
"description": "The type of the Token issued",
"type": "string"
}
},
"required": ["access_token", "expires_in", "token_type"]
}
Example:
{
"access_token":"eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbS92MS4wIiwic3ViIjoidXNlcm5hbWVAZXhhbXBsZS5jb20iLCJhdWQiOlsiKi5leGFtcGxlLmNvbSJdLCJpYXQiOjE1NDg3Nzk0NjAsImV4cCI6MTU0ODc3OTUyMCwic2NvcGUiOiJyZWdpc3RyYXRpb24gcXVlcnkgY29ubmVjdGlvbiIsImNsaWVudF9pZCI6ImhvcHkwZE5SUE5UaUdKRHFQZnFZd0dtdyIsIngtbm1vcy1yZWdpc3RyYXRpb24iOnsicmVhZCI6WyIqIl19LCJ4LW5tb3MtcXVlcnkiOnsicmVhZCI6WyIqIl0sIndyaXRlIjpbInN1YnNjcmlwdGlvbnMvKiJdfSwieC1ubW9zLWNvbm5lY3Rpb24iOnsicmVhZCI6WyIqIl0sIndyaXRlIjpbInNpbmdsZS8qIl19fQ.PQsBE3ZGMrfAJN6ev-2oZ_CNkRFbRGRzuUKJdfpDwaOJc8VdMSmNjehxsKiz67BoLkb_x23D1GrRoQEB4ZGj6_UnPXOpax9xpbE8bQfFGCuCdfzD_u9Ju0nmLzZT1MJk5dj4z3OVKGYq36o8sDPURHizKVJ5aOUihazPxR9gqHXESvn4IWpk951m9dzrYoks4Yyq6yf6K4OkwXpbtr78JQp927ceIocVNAtTbGHo_h0F2uVA_uuCISYLx6C1-8v6zBLXmEevbAZyN3aujEh3qZ8-x7bYHEv5Kq5Kt_aeEesFkor57_KK8OBQaiAfdH6voF6ots_r_z4MkzfH2zjBHw",
"token_type":"Bearer",
"expires_in":60,
"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjUyM2Y0NmVjLWE0MzUtNGVkOS05ODBjLWZlM2Y4YmMwYzY1OCJ9.eyJpc3MiOiJodHRwczovL3NlcnZlci5leGFtcGxlLmNvbS92MS4wIiwic3ViIjoidXNlcm5hbWVAZXhhbXBsZS5jb20iLCJhdWQiOiJodHRwczovL3NlcnZlci5leGFtcGxlL2NvbS92MS4wIiwiaWF0IjoxNTQ4Nzc5NDYwLCJleHAiOjE1NDg3ODEyNjAsInNjb3BlIjoicmVnaXN0cmF0aW9uIHF1ZXJ5IGNvbm5lY3Rpb24iLCJjbGllbnRfaWQiOiJob3B5MGROUlBOVGlHSkRxUGZxWXdHbXcifQ.5_1pQnbCMQn4Z62hmlyqqc-LzsogyOMrRFxy46td368",
"refresh_expires_in":1800
}
HTTP status code 400
Unsuccessful token requests
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Token Error Response",
"description": "Describes the token endpoint's OAuth error response",
"type": "object",
"minItems": 1,
"properties": {
"error": {
"description": "Error Type",
"type": "string",
"enum": ["invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope", "unsupported_token_type"]
},
"error_description": {
"description": "Human-readable ASCII text providing additional information",
"type": "string"
},
"error_uri": {
"description": "A URI identifying a human-readable web page with information about the error",
"type": "string",
"format": "uri"
}
},
"required": ["error"]
}
Example:
{
"error": "invalid_request"
}
HTTP status code 401
Unsuccessful Client Authentication
Secured by Basic Authentication
Secured by JSON Web Token Authentication
options /{token_endpoint_path}
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
JSON Web Key Set endpoint
Request the JSON Web Keys. See RFC 7517.
get /{jwks_uri_path}
Request the JSON Web Keys. See RFC 7517.
URI Parameters
- jwks_uri_path: required(string)
This path is defined by the jwks_uri in the OAuth 2.0 Authorization Server Metadata, as per RFC 8414 Section 2.
Example:
jwks
HTTP status code 200
Successful request to obtain JSON dictionary of available JSON Web Keys to validate token against.
Body
Media type: application/json
Type:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "JWKs Response",
"description": "JSON Web Key Set to validate Access Token",
"type": "object",
"allOf": [
{"$ref": "jwks_schema.json"}
]
}
Example:
{
"keys": [
{
"kty":"EC",
"crv":"P-256",
"x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
"y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
"use":"enc",
"kid":"1"
},
{
"kty":"RSA",
"n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
"e":"AQAB",
"alg":"RS256",
"kid":"2011-04-29"
}
]
}
OAuth 2.0 Authorization endpoint
get /{authorization_endpoint_path}
The client directs the resource owner to this URI, enabling the resource owner to approve the client. See Section 4 of RFC 6749.
URI Parameters
- authorization_endpoint_path: required(string)
This path is defined by the authorization_endpoint in the OAuth 2.0 Authorization Server Metadata, as per RFC 8414 Section 2.
Example:
authorize
Query Parameters
- response_type: required(string)
Type of OAuth 2.0 response. MUST be set to "code"
Example:
response_type=code - client_id: required(string)
The identifier of the client authenticating
Example:
client_id=s6BhdRkqt3 - redirect_uri: required(string)
URI to direct resource owner's user-agent back to clients
Example:
redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - scope: (string)
The scope of the access request
Example:
scope=photos - state: (string)
Value used by client to maintain state between request and callback
Example:
state=xyz - code_challenge: (string)
Derived from the code_verifier - a high-entropy cryptographic random string
- code_challenge_method: (one of plain, S256 - default: plain)
Code verifier transformation method
HTTP status code 200
UI / Web Form for the resource owner to confirm the authorization.
Body
Media type: text/html
Type: file
post /{authorization_endpoint_path}
Means of confirming Resource Owner approval. See RFC 6749.
URI Parameters
- authorization_endpoint_path: required(string)
This path is defined by the authorization_endpoint in the OAuth 2.0 Authorization Server Metadata, as per RFC 8414 Section 2.
Example:
authorize
Query Parameters
- response_type: required(string)
Type of OAuth 2.0 response. MUST be set to "code"
Example:
response_type=code - client_id: required(string)
The identifier of the client authenticating
Example:
client_id=s6BhdRkqt3 - redirect_uri: required(string)
URI to direct resource owner's user-agent back to clients
Example:
redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - scope: (string)
The scope of the access request
Example:
scope=photos - state: (string)
Value used by client to maintain state between request and callback
Example:
state=xyz - code_challenge: (string)
Derived from the code_verifier - a high-entropy cryptographic random string
- code_challenge_method: (one of plain, S256 - default: plain)
Code verifier transformation method
Body
Media type: application/json
Type: object
Properties- confirm: required(boolean)
Boolean comfirmation of Resource Owner authorization.
Note: This is merely an example of one mechanism for obtaining the resource owner's approval. This is not covered in an RFC and is implementation-specific.
Example:
true
HTTP status code 302
Redirection of endpoint to client URI
Headers
- Location: required(string)
The redirect URI with the Authorization Code and State parameters added to the query component of the redirection URI.
Example:
HTTP/1.1 302 Found Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz
options /{authorization_endpoint_path}
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
OAuth 2.0 Token Revocation endpoint (optional)
Endpoint for revoking specific Access/Refresh Tokens. See RFC 7009.
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes
post /{revocation_endpoint_path}
Endpoint for revoking specific Access/Refresh Tokens. See RFC 7009.
This API supports Basic Authentication using client ID and client secret as username and password credentials respectively.
This API supports authentication using a JSON Web Token, signed by a private key which the Authorization Server holds the corresponding public key for.
URI Parameters
- revocation_endpoint_path: required(string)
This path is defined by the revocation_endpoint in the OAuth 2.0 Authorization Server Metadata, as per RFC 8414 Section 2.
Example:
revoke
Headers
- Authorization: required(string)
Colon-seperated, base-64 encoded string, of Client ID and Client Secret
Body
Media type: application/x-www-form-urlencoded
Type: object
Properties- access_token: required(string)
The token (access / refresh) that the client wants to revoke
- token_type_hint: required(one of access_token, refresh_token)
A hint about the type of the token submitted for revocation
HTTP status code 200
the token has been revoked successfully or if the client submitted an invalid token.
Secured by Basic Authentication
Secured by JSON Web Token Authentication
options /{revocation_endpoint_path}
A pre-flight check generally used for Cross-Origin Resource Sharing (CORS) purposes