{
  "openapi": "3.1.0",
  "info": {
    "title": "Gigs Auth API",
    "description": "Gigs Authentication and Authorization API.",
    "contact": {
      "name": "Gigs Support",
      "email": "support@gigs.com"
    },
    "version": "2021-04-28"
  },
  "servers": [
    {
      "url": "https://auth.gigs.com",
      "description": "production"
    }
  ],
  "paths": {
    "/.well-known/oauth-authorization-server": {
      "get": {
        "tags": [
          "OAuth"
        ],
        "operationId": "AuthorizationServerMetadataRetrieve",
        "summary": "Retrieve the Authorization Server Metadata",
        "description": "Retrieve the OAuth 2.0 Authorization Server Metadata describing this\nauthorization server's endpoints and capabilities, as defined by\n[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).\n\nThe response only advertises capabilities that are actually implemented.\nThere is no authorization endpoint, no dynamic client registration, and\nno token revocation or introspection endpoint, so those fields are\nabsent.\n\nThis endpoint is unauthenticated.\n",
        "responses": {
          "200": {
            "description": "The authorization server's metadata. See https://datatracker.ietf.org/doc/html/rfc8414#section-2 for the meaning of each field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/authorizationServerMetadata"
                },
                "examples": {
                  "Example": {
                    "summary": "Example",
                    "value": {
                      "issuer": "https://auth.gigs.com",
                      "token_endpoint": "https://auth.gigs.com/oauth/token",
                      "jwks_uri": "https://auth.gigs.com/.well-known/jwks.json",
                      "grant_types_supported": [
                        "client_credentials"
                      ],
                      "token_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                        "private_key_jwt"
                      ],
                      "token_endpoint_auth_signing_alg_values_supported": [
                        "RS256",
                        "PS256"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "tags": [
          "JSON Web Key Set"
        ],
        "operationId": "JWKSRetrieve",
        "summary": "Retrieve the JSON Web Key Set",
        "description": "Retrieve the JSON Web Key Set (JWKS) used to sign access tokens.",
        "responses": {
          "200": {
            "description": "Returns the JSON Web Key Set (JWKS) object as defined by RFC 7517.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/jwks"
                },
                "examples": {
                  "Example": {
                    "summary": "Example",
                    "value": {
                      "keys": [
                        {
                          "alg": "PS256",
                          "e": "AQAB",
                          "kid": "001b63aab83720e46187661dae2f4400fe77c3db2b3a39410c260cb163997a3c",
                          "kty": "RSA",
                          "n": "z3JEo0_5NfWi473TV_...",
                          "use": "sig"
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "tags": [
          "OAuth"
        ],
        "operationId": "OauthTokenExchange",
        "summary": "Get a token",
        "description": "Get an access token that can be used with the Gigs API.\n\n## Authentication\n\nClients authenticate using one of the following methods.\n\n### `client_secret_basic`\n\nHTTP Basic authentication using the client credentials:\n\n```\nAuthorization: Basic <base64(client_id:client_secret)>\n```\n\n### `private_key_jwt`\n\nA signed JWT client assertion in the request body (OIDC Core 1.0 §9):\n\n```\nclient_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer\nclient_assertion=<signed JWT>\n```\n\nNo `Authorization` header is sent. The assertion's `iss` and `sub`\nclaims must equal the client_id; `aud` must equal\n`https://auth.gigs.com`; and the assertion lifetime must not exceed\n300 seconds.\n",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ],
                    "description": "The grant type to use.",
                    "examples": [
                      "client_credentials"
                    ]
                  },
                  "scope": {
                    "type": "string",
                    "description": "The scope of access requested for the `client_credentials` grant type. Whether this parameter is required depends on the application. Format: `project:{project_id}`.",
                    "examples": [
                      "project:gigs"
                    ]
                  },
                  "client_assertion_type": {
                    "type": "string",
                    "enum": [
                      "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
                    ],
                    "description": "The type of client assertion used to authenticate the client. Required when authenticating with `private_key_jwt`.",
                    "examples": [
                      "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
                    ]
                  },
                  "client_assertion": {
                    "type": "string",
                    "description": "A signed JWT proving possession of the client's private key. Required when `client_assertion_type` is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`."
                  }
                },
                "required": [
                  "grant_type"
                ]
              },
              "examples": {
                "client_secret_basic": {
                  "summary": "client_secret_basic",
                  "value": {
                    "grant_type": "client_credentials",
                    "scope": "project:gigs-project"
                  },
                  "x-auth": {
                    "clientSecretBasic": []
                  }
                },
                "private_key_jwt": {
                  "summary": "private_key_jwt",
                  "value": {
                    "grant_type": "client_credentials",
                    "scope": "project:gigs-project",
                    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
                    "client_assertion": "<signed JWT>"
                  },
                  "x-auth": {}
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Returns an access token which can be used with the Gigs API.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string",
                      "description": "The access token which grants access to the Gigs API. Must not be parsed or modified. Should not be persisted.",
                      "examples": [
                        "SdwEV5cN8ivUbxsUBveYRwFE09m7JXSsmZMPLd5xmW5STaYfrG3W2PgKgInRWUKX"
                      ]
                    },
                    "expires_in": {
                      "type": "integer",
                      "description": "The lifetime in seconds of the access token.",
                      "examples": [
                        3600
                      ]
                    },
                    "token_type": {
                      "type": "string",
                      "const": "Bearer",
                      "description": "The type of the access token is always `Bearer`."
                    }
                  },
                  "required": [
                    "access_token",
                    "expires_in",
                    "token_type"
                  ]
                },
                "examples": {
                  "Example - Full": {
                    "summary": "Example - Full",
                    "value": {
                      "access_token": "SdwEV5cN8ivUbxsUBveYRwFE09m7JXSsmZMPLd5xmW5STaYfrG3W2PgKgInRWUKX",
                      "expires_in": 3600,
                      "token_type": "Bearer"
                    }
                  },
                  "Example - Required": {
                    "summary": "Example - Required",
                    "value": {
                      "access_token": "SdwEV5cN8ivUbxsUBveYRwFE09m7JXSsmZMPLd5xmW5STaYfrG3W2PgKgInRWUKX",
                      "expires_in": 3600,
                      "token_type": "Bearer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/invalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/tooManyRequests"
          }
        },
        "security": [
          {
            "clientSecretBasic": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "authorizationServerMetadata": {
        "type": "object",
        "title": "Authorization Server Metadata",
        "description": "OAuth 2.0 Authorization Server Metadata as defined by RFC 8414.\n\nOnly the metadata that describes capabilities we actually implement is\nadvertised. Fields for unimplemented features are deliberately omitted\nrather than populated with placeholders:\n\n- `authorization_endpoint` — we implement no redirect-based authorization\n  endpoint. RFC 8414 section 2 permits omitting it when no supported grant\n  type uses it.\n- `registration_endpoint` — dynamic client registration (RFC 7591) is not\n  supported; clients are registered out of band.\n- `revocation_endpoint` / `introspection_endpoint` — access tokens are\n  self-contained JWTs that cannot be revoked and do not need introspection.\n- `scopes_supported` — the scope space is `project:{project_id}`, so the\n  set of valid values is per-application and cannot be enumerated here.\n- `code_challenge_methods_supported` — PKCE (RFC 7636) only applies to the\n  authorization code grant, which we do not support.\n",
        "properties": {
          "issuer": {
            "type": "string",
            "description": "The authorization server's issuer identifier. Matches the `iss` claim of every token we issue. When authenticating with `private_key_jwt`, this is also the value of the client assertion's `aud` claim.",
            "examples": [
              "https://auth.gigs.com"
            ]
          },
          "token_endpoint": {
            "type": "string",
            "description": "URL of the OAuth 2.0 Token Endpoint.",
            "examples": [
              "https://auth.gigs.com/oauth/token"
            ]
          },
          "jwks_uri": {
            "type": "string",
            "description": "URL of the JSON Web Key Set (JWKS) document containing the keys that sign our access tokens.",
            "examples": [
              "https://auth.gigs.com/.well-known/jwks.json"
            ]
          },
          "grant_types_supported": {
            "type": "array",
            "description": "List of the supported OAuth 2.0 grant type values.",
            "items": {
              "type": "string",
              "examples": [
                "client_credentials"
              ]
            },
            "examples": [
              [
                "client_credentials"
              ]
            ]
          },
          "token_endpoint_auth_methods_supported": {
            "type": "array",
            "default": [
              "client_secret_basic",
              "private_key_jwt"
            ],
            "description": "List of client authentication methods supported by the Token Endpoint.",
            "items": {
              "type": "string",
              "examples": [
                "private_key_jwt"
              ]
            },
            "examples": [
              [
                "client_secret_basic",
                "private_key_jwt"
              ]
            ]
          },
          "token_endpoint_auth_signing_alg_values_supported": {
            "type": "array",
            "default": [
              "RS256",
              "PS256"
            ],
            "description": "List of JWS signing algorithms supported by the Token Endpoint for the signature on the JWT used to authenticate the client at the Token Endpoint for the `private_key_jwt` authentication method.",
            "items": {
              "type": "string",
              "examples": [
                "PS256"
              ]
            },
            "examples": [
              [
                "RS256",
                "PS256"
              ]
            ]
          }
        },
        "required": [
          "issuer",
          "token_endpoint",
          "jwks_uri",
          "grant_types_supported",
          "token_endpoint_auth_methods_supported",
          "token_endpoint_auth_signing_alg_values_supported"
        ]
      },
      "jwk": {
        "type": "object",
        "title": "JWK",
        "description": "A JSON Web Key represents a cryptographic key. The members of this object\nrepresent properties of the key, including its value, as defined by\n[RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).\n",
        "properties": {
          "alg": {
            "type": "string",
            "enum": [
              "PS256",
              "RS256"
            ],
            "description": "The \"alg\" (algorithm) parameter identifies the algorithm intended for use with the key."
          },
          "e": {
            "type": "string",
            "description": "The \"e\" parameter identifies the exponent of a RSA key.",
            "examples": [
              "AQAB"
            ]
          },
          "kid": {
            "type": "string",
            "description": "The \"kid\" (key ID) parameter is used to match a specific key.",
            "examples": [
              "001b63aab83720e46187661dae2f4400fe77c3db2b3a39410c260cb163997a3c"
            ]
          },
          "kty": {
            "type": "string",
            "const": "RSA",
            "description": "The \"kty\" (key type) parameter identifies the cryptographic algorithm family used with the key. At this point only `RSA` is supported."
          },
          "n": {
            "type": "string",
            "description": "The \"n\" parameter identifies the modulus of a RSA key.",
            "examples": [
              "z3JEo0_5NfWi473TV_..."
            ]
          },
          "use": {
            "type": "string",
            "const": "sig",
            "description": "The \"use\" (public key use) parameter identifies the intended use of the public key. At this point only `sig` (signature) keys are supported."
          }
        },
        "required": [
          "alg",
          "e",
          "kid",
          "kty",
          "n",
          "use"
        ]
      },
      "jwks": {
        "type": "object",
        "title": "JWKS",
        "description": "JSON Web Key Set (JWKS) is a JSON object that represents a set of JSON Web Keys\n(JWKs) as defined by [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).\n",
        "properties": {
          "keys": {
            "type": "array",
            "description": "The list of JWKs used to sign JWTs returned by https://auth.gigs.com.",
            "items": {
              "$ref": "#/components/schemas/jwk"
            }
          }
        },
        "required": [
          "keys"
        ]
      }
    },
    "responses": {
      "invalidRequest": {
        "description": "Invalid request errors arise when the request was malformed or was missing required properties.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "A single [error code](https://developers.gigs.com/api/error-handling).",
                  "examples": [
                    "invalid_client"
                  ]
                },
                "error_description": {
                  "type": "string",
                  "description": "Human-readable description providing additional information, used to assist in understanding the error that occurred.",
                  "examples": [
                    "Client authentication failed."
                  ]
                }
              },
              "required": [
                "error",
                "error_description"
              ]
            },
            "examples": {
              "Example": {
                "summary": "Example",
                "value": {
                  "error": "invalid_client",
                  "error_description": "Client authentication failed."
                }
              }
            }
          }
        }
      },
      "unauthorized": {
        "description": "Unauthorized errors arise when the client is invalid or unknown.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "A single [error code](https://developers.gigs.com/api/error-handling).",
                  "examples": [
                    "invalid_client"
                  ]
                },
                "error_description": {
                  "type": "string",
                  "description": "Human-readable description providing additional information, used to assist in understanding the error that occurred.",
                  "examples": [
                    "Client authentication failed."
                  ]
                }
              },
              "required": [
                "error",
                "error_description"
              ]
            },
            "examples": {
              "Example": {
                "summary": "Example",
                "value": {
                  "error": "invalid_client",
                  "error_description": "Client authentication failed."
                }
              }
            }
          }
        }
      },
      "tooManyRequests": {
        "description": "Too-many requests errors arise when the client has sent too many requests in a given amount of time and was rate-limited.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "A single [error code](https://developers.gigs.com/api/error-handling).",
                  "examples": [
                    "invalid_client"
                  ]
                },
                "error_description": {
                  "type": "string",
                  "description": "Human-readable description providing additional information, used to assist in understanding the error that occurred.",
                  "examples": [
                    "Client authentication failed."
                  ]
                }
              },
              "required": [
                "error",
                "error_description"
              ]
            },
            "examples": {
              "Example": {
                "summary": "Example",
                "value": {
                  "error": "invalid_client",
                  "error_description": "Client authentication failed."
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "clientSecretBasic": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "security": [],
  "tags": [
    {
      "name": "JSON Web Key Set",
      "description": "List the JSON Web Key Set (JWKS) used to sign access tokens"
    },
    {
      "name": "OAuth",
      "description": "Get access tokens with OAuth 2.0"
    }
  ]
}