openapi-spec.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Token Exchange as a Service (Texas)",
    "description": "Texas implements OAuth token fetch, exchange, and validation, so that you don't have to.",
    "contact": {
      "name": "Nais",
      "url": "https://nais.io"
    },
    "license": {
      "name": ""
    },
    "version": "1.0.0"
  },
  "paths": {
    "/api/v1/introspect": {
      "post": {
        "tags": [
          "Endpoints"
        ],
        "operationId": "introspect",
        "requestBody": {
          "description": "Validate a token and return its claims and metadata. The response object's _active_ field will be set to either true or false for valid and invalid tokens, respectively. The identity provider determines which claims are returned. Please see the examples and/or Nais documentation for details.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntrospectRequest"
              },
              "examples": {
                "Token introspection": {
                  "value": {
                    "identity_provider": "tokenx",
                    "token": "eyJraWQiOiJ0b2tlbngiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJlMDE1NTQyYy0wZjgxLTQwZjUtYmJkOS03YzNkOTM2NjI5OGYiLCJhdWQiOiJteS10YXJnZXQiLCJuYmYiOjE3MzA5NzcyOTMsImF6cCI6InlvbG8iLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvdG9rZW54IiwiZXhwIjoxNzMwOTgwODkzLCJpYXQiOjE3MzA5NzcyOTMsImp0aSI6ImU3Y2JhZGMzLTZiZGEtNDljMC1hMTk2LWM0NzMyOGRhODgwZSIsInRpZCI6InRva2VueCJ9.SIme9o5YE6pZXT9IMAx5upV3V4ww_TnDlqZG203pkySPBd_VqNGBXzOKHeOasIDpXEMlf8Yc-1nKgySjGOT3c46PIHEUrhQFXF6s9OpJAYAwy7L2n2DIFfEOLt8EpwSpM5hWDwnGpSdvebWlmoaA3ImFEB5dtnxLrVG-7dYEEzZjMfBOKFWrPp03FTO4qKOJUqCZR0tmZRmcPzymPWFIMjP2FTj6iz9zai93dhQmdvNVMGL9HBXF6ewKf_CTlUIx9XpwI2M-dhlyH2PIxyhix7Amuff_mHuEHTuCAFqMfjon-F438uyZmgicyrvhoUGxV8W1PfZEiLIv0RBeWRJ9gw"
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/IntrospectRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntrospectResponse"
                },
                "examples": {
                  "Invalid token": {
                    "value": {
                      "active": false,
                      "error": "token is expired"
                    }
                  },
                  "Valid token": {
                    "value": {
                      "active": true,
                      "aud": "my-target",
                      "azp": "yolo",
                      "exp": 1730980893,
                      "iat": 1730977293,
                      "iss": "http://localhost:8080/tokenx",
                      "jti": "e7cbadc3-6bda-49c0-a196-c47328da880e",
                      "nbf": 1730977293,
                      "sub": "e015542c-0f81-40f5-bbd9-7c3d9366298f",
                      "tid": "tokenx"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/token": {
      "post": {
        "tags": [
          "Endpoints"
        ],
        "operationId": "token",
        "requestBody": {
          "description": "Request a machine-to-machine token from the specified identity provider and for a given target.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenRequest"
              },
              "examples": {
                "Force renewal of token for Azure AD": {
                  "value": {
                    "identity_provider": "azuread",
                    "skip_cache": true,
                    "target": "api://cluster.namespace.application/.default"
                  }
                },
                "Generate a token for Azure AD": {
                  "value": {
                    "identity_provider": "azuread",
                    "target": "api://cluster.namespace.application/.default"
                  }
                },
                "Generate a token for Maskinporten": {
                  "value": {
                    "identity_provider": "maskinporten",
                    "resource": "http://resource.example/api",
                    "target": "altinn:serviceowner/rolesandrights"
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/TokenRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                },
                "examples": {
                  "Token response": {
                    "value": {
                      "access_token": "eyJraWQiOiJ0b2tlbngiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIyZjNjM2Y4YS03NTYwLTRjNWMtYmM4My0yNzVhY2Q1MWU1N2YiLCJhdWQiOiJteS10YXJnZXQiLCJuYmYiOjE3MzA5NzYxODQsImF6cCI6InlvbG8iLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvdG9rZW54IiwiZXhwIjoxNzMwOTc5Nzg0LCJpYXQiOjE3MzA5NzYxODQsImp0aSI6IjBmNTM3M2YyLThjYmUtNDczOS05ZDU1LWY5MzE4YmFiNWQ2NyIsInRpZCI6InRva2VueCJ9.aQ-2TcdDRkWXbi3en6eMwzjSkYLH-S6aiAyss8MkkAPT_RGlZF_eCKFFsaKJ9YwQAzs4BN_d13W-xejPf6B_3Mn7xasDX_5r-M5ZwXxPWkRe5daqdqznF-vPAnIIjmqynjEYgijn79Rajorcu1sgW4bsrByp1lXNhntHar-8x62S_5oY40tEjIAHv7q2zKRxoKxKlcNpnLpKnZWrkJj7SboiCpGWc-W4JtcnNTHgKRXcFVfXSGD6EhHQ2HLDtmWJkk8NHTnjLI8IRt0mrkOs_nt2jNDDpH9ViqlWi7FOwi4C0OSfGHGukDYOeRc3vICgFGHyi0G6Avq9YXtuAP62_A",
                      "expires_in": 3599,
                      "token_type": "Bearer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/token/exchange": {
      "post": {
        "tags": [
          "Endpoints"
        ],
        "operationId": "token_exchange",
        "requestBody": {
          "description": "Exchange a user's token for a machine token, scoped to the given target. The returned token allows your application to act on behalf of the user.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenExchangeRequest"
              },
              "examples": {
                "Exchange a token using Azure AD": {
                  "value": {
                    "identity_provider": "azuread",
                    "target": "api://cluster.namespace.application/.default",
                    "user_token": "eyJraWQiOiJhenVyZWFkIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI1ZDYzMDliNi05OGUzLTQ1ODAtYTQwNS02MDExYzhhNjExYzgiLCJhdWQiOiJkZWZhdWx0IiwibmJmIjoxNzMwOTc4MjQyLCJhenAiOiJ5b2xvIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F6dXJlYWQiLCJleHAiOjE3MzA5ODE4NDIsImlhdCI6MTczMDk3ODI0MiwianRpIjoiZTU4ZGM2ZjctZjQ0NC00YzcxLThlNzAtNzRhNWY1MTRlZDAwIiwidGlkIjoiYXp1cmVhZCJ9.KhySKFTJVaE6tYhsxCZonYMXv4fKwjtOI4YIAIoOs3DwaXoynTvy2lgiHSfisq-jLTJFGf9eGNbvwc3jUtypclVpYy_8d3xbvuu6jrOA1zWYagZjYr1FNN1g8tlF0SXjtkK_Bg-eZusLnEEbrZK1KnQRWN0I5fXqS7-IVe07hKTOE1teg7of2nCjfJ-iOXhf1mkXqCoUfSbJuUX2PEUs0b9yXAh_J-5P75T6130KBfRw5T5gYI0Kab3u2vm6t-ihT2Kz0aMkUGv_39myDgiwP4TV2vt4PhUiwefPo7KD-4_dkHc7Q5xUv-DWgTLUfXL2lOWf2d0C5tVExLB86jq8hw"
                  }
                },
                "Exchange a token using TokenX": {
                  "value": {
                    "identity_provider": "tokenx",
                    "target": "cluster:namespace:application",
                    "user_token": "eyJraWQiOiJpZHBvcnRlbiIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIxOTQyMmVhNC04ZWUwLTQ0YTYtOThjNi0zODc0MjAyN2YyYWQiLCJhdWQiOiJkZWZhdWx0IiwibmJmIjoxNzMwOTc4MzgwLCJhenAiOiJ5b2xvIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2lkcG9ydGVuIiwiZXhwIjoxNzMwOTgxOTgwLCJpYXQiOjE3MzA5NzgzODAsImp0aSI6IjBhMDU5MDc3LTQwNzEtNDdlYS04MmM2LTU2NTY2OTk3Nzg3MiIsInRpZCI6ImlkcG9ydGVuIn0.JwgvrhPMRMaNJngiR6hzHfhg5Qy-yV4zuAtxRRvdjX4g2cBmsWj305U-lHJGsozjFhpGpA0lAn16bD3l1Z6x7CsO6kbQEwKQiJE9gB61RwSUEjV4-RbpVrKMJwppQg8gPLrb4SbTjjkylD7B9CfPiIZYtCNr6d-J0lupYiB7IlK7anUImCv7RqXTuhH0aklVpVmxOZRhzHJ6_WfhWS54MysZmeRZwOsSO-ofkrcznFFaArS1ODfrYgHx4dgVBjkE7RTcLP7nuwNtvbLg9ZVvIAT4Xh-3fu0pCL9NXoDiqBsQ0SukBAlBFfWQBFu1-34-bXkfRz2RgCR964WbKUQ8gQ"
                  }
                },
                "Force renewal of token using Azure AD": {
                  "value": {
                    "identity_provider": "azuread",
                    "skip_cache": true,
                    "target": "api://cluster.namespace.application/.default",
                    "user_token": "eyJraWQiOiJhenVyZWFkIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI1ZDYzMDliNi05OGUzLTQ1ODAtYTQwNS02MDExYzhhNjExYzgiLCJhdWQiOiJkZWZhdWx0IiwibmJmIjoxNzMwOTc4MjQyLCJhenAiOiJ5b2xvIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F6dXJlYWQiLCJleHAiOjE3MzA5ODE4NDIsImlhdCI6MTczMDk3ODI0MiwianRpIjoiZTU4ZGM2ZjctZjQ0NC00YzcxLThlNzAtNzRhNWY1MTRlZDAwIiwidGlkIjoiYXp1cmVhZCJ9.KhySKFTJVaE6tYhsxCZonYMXv4fKwjtOI4YIAIoOs3DwaXoynTvy2lgiHSfisq-jLTJFGf9eGNbvwc3jUtypclVpYy_8d3xbvuu6jrOA1zWYagZjYr1FNN1g8tlF0SXjtkK_Bg-eZusLnEEbrZK1KnQRWN0I5fXqS7-IVe07hKTOE1teg7of2nCjfJ-iOXhf1mkXqCoUfSbJuUX2PEUs0b9yXAh_J-5P75T6130KBfRw5T5gYI0Kab3u2vm6t-ihT2Kz0aMkUGv_39myDgiwP4TV2vt4PhUiwefPo7KD-4_dkHc7Q5xUv-DWgTLUfXL2lOWf2d0C5tVExLB86jq8hw"
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/TokenExchangeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                },
                "examples": {
                  "Token response": {
                    "value": {
                      "access_token": "eyJraWQiOiJhenVyZWFkIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI1ZDYzMDliNi05OGUzLTQ1ODAtYTQwNS02MDExYzhhNjExYzgiLCJhdWQiOiJteS10YXJnZXQiLCJuYmYiOjE3MzA5NzgyNDIsImF6cCI6InlvbG8iLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXp1cmVhZCIsImV4cCI6MTczMDk4MTg0MiwiaWF0IjoxNzMwOTc4MjQyLCJqdGkiOiJkNDQ4NTRjNC1iYmZhLTRmZTMtYTMyNC0xZDQyNjdkZjdjZjYiLCJ0aWQiOiJhenVyZWFkIn0.fqTw40aXkzGqet7mMRfK-8cUICzBW7SKIb5UOh6sTvrqprJEtF1HG8MLRcjgjEVwShNkYzJiUZzOC7GSxcuYSiDFg9rboR0QPvTtYsPHWjBGCpvo7lJl27oyqS7QUS83Gsc3oGbCYxc_f4TWOVP8j6pVVZjHAietUd7A-KSwck_YkhmJxKpx7HUhK11AOLjcUlJzb_GpAf1zbog9aIsg9gg9DvWIXtyGqmmBAjr69faFzg7s6KssAQS6A3Qcn19nHC2-J_Ic5q-b8gIDGTq2w62GukbYjyjI7pMYYE04QPPmFI1jdKS9QygW8zX2wQ-10Tc4o4BmMMRjp1RvMm3t6Q",
                      "expires_in": 3599,
                      "token_type": "Bearer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "RFC 6749 error response from section 5.2.",
        "required": [
          "error",
          "error_description"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/OAuthErrorCode"
          },
          "error_description": {
            "type": "string"
          }
        }
      },
      "IdentityProvider": {
        "type": "string",
        "description": "Identity providers for use with token fetch, exchange and introspection.",
        "enum": [
          "azuread",
          "tokenx",
          "maskinporten",
          "idporten"
        ]
      },
      "IntrospectRequest": {
        "type": "object",
        "description": "This data type holds the OAuth token that will be validated in the introspect endpoint.",
        "required": [
          "token",
          "identity_provider"
        ],
        "properties": {
          "identity_provider": {
            "$ref": "#/components/schemas/IdentityProvider"
          },
          "token": {
            "type": "string"
          }
        }
      },
      "IntrospectResponse": {
        "type": "object",
        "description": "Based on RFC 7662 introspection response from section 2.2.\n\nClaims from the original token are copied verbatim to the introspection response as additional properties.\nThe claims present depend on the identity provider.\nPlease refer to the Nais documentation for details:\n\n- [Azure AD](https://doc.nais.io/auth/entra-id/reference/#claims)\n- [IDPorten](https://doc.nais.io/auth/idporten/reference/#claims)\n- [Maskinporten](https://doc.nais.io/auth/maskinporten/reference/#claims)\n- [TokenX](https://doc.nais.io/auth/tokenx/reference/#claims)",
        "required": [
          "active"
        ],
        "properties": {
          "active": {
            "type": "boolean",
            "description": "Indicates whether the token is valid. If this field is _false_,\nthe token is invalid and *must* be rejected."
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "If the token is invalid, this field contains the reason."
          }
        },
        "additionalProperties": {
          "description": "Claims from valid tokens are contained in the introspection response, but only if the token is valid."
        }
      },
      "OAuthErrorCode": {
        "type": "string",
        "enum": [
          "invalid_request",
          "invalid_client",
          "invalid_grant",
          "unauthorized_client",
          "unsupported_grant_type",
          "invalid_scope",
          "server_error"
        ]
      },
      "TokenExchangeRequest": {
        "type": "object",
        "description": "Use this data type to exchange a user token for a machine token.",
        "required": [
          "target",
          "identity_provider",
          "user_token"
        ],
        "properties": {
          "identity_provider": {
            "$ref": "#/components/schemas/IdentityProvider"
          },
          "skip_cache": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Force renewal of token. Defaults to false if omitted."
          },
          "target": {
            "type": "string",
            "description": "Scope or identifier for the target application."
          },
          "user_token": {
            "type": "string",
            "description": "The user's access token, usually found in the _Authorization_ header in requests to your application."
          }
        }
      },
      "TokenRequest": {
        "type": "object",
        "description": "Use this data type to request a machine token.",
        "required": [
          "target",
          "identity_provider"
        ],
        "properties": {
          "identity_provider": {
            "$ref": "#/components/schemas/IdentityProvider"
          },
          "resource": {
            "type": [
              "string",
              "null"
            ],
            "description": "Resource indicator for audience-restricted tokens (RFC 8707)."
          },
          "skip_cache": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Force renewal of token. Defaults to false if omitted."
          },
          "target": {
            "type": "string",
            "description": "Scope or identifier for the target application."
          }
        }
      },
      "TokenResponse": {
        "type": "object",
        "description": "RFC 6749 token response from section 5.1.",
        "required": [
          "access_token",
          "token_type",
          "expires_in"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "expires_in": {
            "type": "integer",
            "description": "Token expiry in seconds. Useful for caching purposes.",
            "minimum": 0
          },
          "token_type": {
            "$ref": "#/components/schemas/TokenType"
          }
        }
      },
      "TokenType": {
        "type": "string",
        "description": "Token type is always Bearer, but this might change in the future.",
        "enum": [
          "Bearer"
        ]
      }
    }
  }
}