{
  "openapi": "3.0.1",
  "info": {
    "title": "Auth",
    "description": "This API allows you to request authentication tokens. You can also use it to generate secure URLs that are used in granting customer access to the Tilia services.",
    "contact": {
      "name": "Tilia, Inc.",
      "url": "https://lindenlab.com",
      "email": "tilia@lindenlab.com"
    },
    "license": {
      "name": "Tilia, Inc.",
      "url": "https://www.tilia-inc.com/contact/"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://auth.staging.tilia-inc.com"
    }
  ],
  "paths": {
    "/token": {
      "post": {
        "summary": "Request access token",
        "description": "An Access Token is a string that enables Tilia to verify that a request belongs to an authorized session. Requesting an access token requires the client ID and secret you obtained when registering as a Tilia integrator. The returned token can then be used to to make API calls.",
        "operationId": "getToken",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "required": [
                  "client_id",
                  "client_secret",
                  "grant_type",
                  "scope"
                ],
                "type": "object",
                "properties": {
                  "client_id": {
                    "type": "string",
                    "description": "Your Tilia client ID.",
                    "format": "UUID4",
                    "example": "3f2bfe5b-19b8-41c1-88d7-70a1586bce94"
                  },
                  "client_secret": {
                    "type": "string",
                    "description": "Your Tilia client secret.",
                    "format": "UUID4",
                    "example": "9bc00ca4-937e-4946-bdb5-0814b603334d"
                  },
                  "grant_type": {
                    "type": "string",
                    "description": "The type of token you're requesting. Must have a value of `client_credentials`.",
                    "example": "client_credentials"
                  },
                  "scope": {
                    "type": "array",
                    "description": "The scopes for the token. Refer to the documentation of the endpoint you are calling for the required scope(s).",
                    "items": {
                      "type": "string",
                      "example": "write_registrations,write_user_tokens,user_info"
                    }
                  }
                }
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string",
                      "description": "The Tilia access token.",
                      "example": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiIiwiY2xpZW50X2lkIjoiMDRhZmJlMTctY2RlNi00OTlkLThlMTctZGExZjgwNmU3YzRkIiwiZXhwIjoxNjAwNTY0NTc2LCJpYXQiOjE2MDA1NjA5NzYsImludGVncmF0b3IiOiJ1cGxhbmQiLCJqdGkiOiIxM2Y1NDQ1Mi1kMTI4LTRmZDItODc0Ny01ZmI4NWEwYjQwZWUiLCJuYmYiOjAsInNjb3BlcyI6WyJkZWxldGVfd2FsbGV0IiwiY3JlYXRlX25vbmNlIiwicmVhZF9ub25jZSIsImRlbGV0ZV9ub25jZSIsInJlYWRfcGF5bWVudF9tZXRob2RzIiwid3JpdGVfcmVnaXN0cmF0aW9ucyIsIndyaXRlX3VzZXJfdG9rZW5zIiwidXNlcl9pbmZvIiwid3JpdGVfaW52b2ljZXMiLCJyZWFkX2t5Y3MiLCJ3cml0ZV9yZWdpc3RyYXRpb25fcHJvdmlkZXJfZGF0YSIsInNlYXJjaF9hY2NvdW50cyIsImNoYW5nZV9hY2NvdW50cyIsImJsb2NrX2FjY291bnRzIiwiY3JlYXRlX3dhbGxldCIsInJlYWRfaW52b2ljZXMiLCJyZWFkX3dhbGxldCIsIndyaXRlX3Byb2Nlc3NfY3JlZGl0cyIsInJlYWRfcHJvY2Vzc19jcmVkaXRzIl0sInRva2VuX3R5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJ1c2VybmFtZSI6IiJ9.WQo3tl1zHC2CJCJjohONiCtaPXbgnvpOqCV0Bv4sxubYiNuIa9J8j9BKTagdbd3kLHnKJLzW083mdR3UzPQbOSvBv0yzZDd-pjAnD5D0GF4y49ZOFLb2Kl_qy2c-66-D9BAS1ilwATHTiWtBcHzfh7VfTu-w9Fs3RLCHchsP0ioPsOcWzJ1BmkeuYwxXVYeaGE8vL5z26BGovFOC_SAl-V3UQFq_PnwNsame_ksKus6ayXahAXOkDyTXJkCxHHkc-08VW-JZyWWq0tQkdvZ7_H9CTThFQQ_ByCmVF9bhmf"
                    },
                    "token_type": {
                      "type": "string",
                      "description": "The token type. (e.g. `Bearer`)",
                      "example": "Bearer"
                    },
                    "expires_in": {
                      "type": "string",
                      "description": "The token expiration time, in seconds.",
                      "example": "3600"
                    },
                    "scope": {
                      "type": "string",
                      "description": "The requested scope(s).",
                      "example": "write_registrations,write_user_tokens,user_info"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "The error code.",
                      "example": "unsupported_grant_type"
                    },
                    "error_description": {
                      "type": "string",
                      "description": "A short, human-readable description of the failure.",
                      "example": "The authorization grant type is not supported by the authorization server."
                    },
                    "scope": {
                      "type": "string",
                      "description": "The requested scope(s).",
                      "example": "write_registrations,write_user_tokens,user_info"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Service unavailable or server error"
          }
        },
        "security": [],
        "x-codegen-request-body-name": "userInfo"
      }
    },
    "/authorize/user": {
      "post": {
        "summary": "Request client redirect URL or password token",
        "description": "By default, generates a temporary page that allows a user to visit and have a browser session set.\nThis is typically the first step in directing the user to a Tilia web UI, such as those presented in the payments or payouts flows.\nAfter calling this endpoint, redirect the client's browser to the URL in the response payload. More info about the web UI can be found [here](../../../web-uis/index.md).\n\nAlternatively, if `return_token` is set to true, the response payload will contain the key `token` whose value is a password token string that can be passed directly to other API calls. This is useful for clients that are not browser-based.",
        "operationId": "AuthorizeUserHandler",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "required": [
                  "account_id"
                ],
                "type": "object",
                "properties": {
                  "account_id": {
                    "allOf": [
                      {
                        "description": "The customer's Tilia `account_id`"
                      },
                      {
                        "$ref": "#/components/schemas/AccountId"
                      }
                    ]
                  },
                  "return_token": {
                    "type": "boolean",
                    "description": "If true, a Tilia oauth token will be returned in the response payload rather than a URL redirect. Defaults to false."
                  },
                  "mechanism": {
                    "type": "string",
                    "description": "JWT created for the account_id supplied in the request body. NOTE: this only works if the mechanism is `tilia_hosted`.",
                    "example": "tilia_hosted"
                  },
                  "flow": {
                    "type": "string",
                    "description": "Indicates which pub hosting flow to use. NOTE: this only works if the mechanism is `tilia_hosted`.",
                    "example": "addcard"
                  },
                  "token_expiration_seconds": {
                    "type": "string",
                    "description": "An optional field indicating how long, in seconds, the token lastes",
                    "example": 30
                  }
                }
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "The status of the request, either `Success` or `Failure`.",
                      "x-go-name": "Status",
                      "example": "Success"
                    },
                    "message": {
                      "type": "array",
                      "description": "An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.",
                      "items": {
                        "type": "string",
                        "example": null
                      },
                      "x-go-name": "Message"
                    },
                    "codes": {
                      "type": "array",
                      "description": "An array of failure reason codes. If the request was successful, this array will be empty.",
                      "items": {
                        "type": "string",
                        "example": null
                      },
                      "x-go-name": "Codes"
                    },
                    "payload": {
                      "type": "object",
                      "properties": {
                        "nonce_auth_id": {
                          "type": "string",
                          "description": "The authorization nonce ID. Not present if `return_token` was set to true.",
                          "maxLength": 36,
                          "example": "80b4ff4b-320c-49b3-addf-b8e2e9b13b8c"
                        },
                        "redirect": {
                          "type": "string",
                          "description": "The URL to redirect the client's browser to. Not present if `return_token` was set to true.",
                          "x-go-name": "Redirect",
                          "format": "URL",
                          "example": "https://web.tilia-inc.com/ui/appauth/80b4ff4b-320c-49b3-addf-b8e2e9b13b8c"
                        },
                        "token": {
                          "type": "string",
                          "description": "The password token. Only present if `return_token` was set to true."
                        }
                      },
                      "x-go-name": "Payload"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. Invalid JSON in request body, or account_id is invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "Failure",
                  "message": [],
                  "codes": [],
                  "payload": "account_id is invalid (ebcbc9c4-7c1b-47df-9ec4-bef3f37c592ff)"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized access."
          },
          "403": {
            "description": "Access forbidden. The account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "Failure",
                  "message": [],
                  "codes": [],
                  "payload": "account is blocked (682c8d3e-75ad-4d10-8b1a-1e1571234561)"
                }
              }
            }
          },
          "500": {
            "description": "Service unavailable or server error"
          }
        },
        "security": [
          {
            "tilia_auth": [
              "write_user_tokens"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "tilia_auth": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://auth.staging.tilia-inc.com/token",
            "scopes": {}
          }
        }
      }
    },
    "schemas": {
      "AccountId": {
        "type": "string",
        "maxLength": 36,
        "example": "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b"
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "The status of the request, either `Success` or `Failure`.",
            "x-go-name": "Status"
          },
          "message": {
            "type": "array",
            "description": "An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.",
            "items": {
              "type": "string"
            },
            "x-go-name": "Message"
          },
          "codes": {
            "type": "array",
            "description": "An array of failure reason codes. If the request was successful, this array will be empty.",
            "items": {
              "type": "string"
            },
            "x-go-name": "Codes"
          },
          "payload": {
            "type": "string",
            "description": "The response payload.",
            "x-go-name": "Payload"
          }
        }
      }
    }
  }
}