> ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # start the process of obtaining a JWT > This is an oauth2 compliant authorize endpoint (see https://tools.ietf.org/html/rfc6749) with the following limitations: - Only grant code flow is allowed - PKCE is mandatory i.e. you must generate a code_verifier (a randomly generated secret) and include its url safe base64 encoded SHA256 hash as the code_challenge parameter - Only the S256 code challenge method is supported - The redirect URI must be set to urn:ietf:wg:oauth:2.0:oob:auto This api returns a grant code that can then be exchanged for a JWT This will create a new profile in the Mapp Fashion database and should therefore only be used if no refresh token is available. code_challenge is constructed in the following manner: - Pick a random code_verifier value, for example 1tBnEmtSImyCykPHxHYBdzpSFhKEj0Q1LuiHd4fdDlY - code challenge = Base64-url-encode(SHA256(code_verifier)): p7CN1Zi4o5ARn1mYNvNFvj2r5cKkr2k6y7a573eHJXQ in the example above For more details on PKCE see https://tools.ietf.org/html/rfc7636, appendix A has the definition of base64-url-encode ## OpenAPI ````json GET /oauth/authorize { "openapi": "3.0.4", "info": { "title": "Mapp Fashion API", "description": "Mapp Fashion recommendation API.\n\n**Host:** there is no shared API host. A dedicated host is configured per partner and supplied during onboarding. All paths below are relative to that host.\n\nTwo versions are available in parallel. **v1** (`/api/...`) covers the established endpoints and is fully maintained, with no deprecation planned. **v2** (`/api/v2/...`) standardizes the inputs and provides one endpoint per recommendation type. New integrations should use v2 wherever a v2 endpoint exists. See Recommendation Strategy for which endpoint to use when.\n", "version": "13" }, "servers": [ { "url": "/api" } ], "security": [ { "api_key": [] }, { "api_key": [], "user_token": [] } ], "tags": [ { "name": "Items", "description": "Operations for retrieving recommendations or items related to one or more seed items" }, { "name": "Items (v2)", "description": "v2: one endpoint per recommendation type, identifiers passed as parameters" }, { "name": "Recommendations", "description": "Operations about recommendations" }, { "name": "Recommendations (v2)", "description": "v2: facetted recommendations in the v2 response format" }, { "name": "Authorization", "description": "Operations for obtaining or refreshing JWTs" } ], "paths": { "/oauth/authorize": { "get": { "tags": [ "Authorization" ], "summary": "start the process of obtaining a JWT", "description": "This is an oauth2 compliant authorize endpoint (see https://tools.ietf.org/html/rfc6749) with the following limitations:\n\n- Only grant code flow is allowed\n- PKCE is mandatory i.e. you must generate a code_verifier (a randomly generated secret) and include its url safe base64 encoded SHA256 hash as the code_challenge parameter\n- Only the S256 code challenge method is supported\n- The redirect URI must be set to urn:ietf:wg:oauth:2.0:oob:auto\n\nThis api returns a grant code that can then be exchanged for a JWT\n\nThis will create a new profile in the Mapp Fashion database and should therefore only be used if no refresh token is available.\n\ncode_challenge is constructed in the following manner:\n\n- Pick a random code_verifier value, for example 1tBnEmtSImyCykPHxHYBdzpSFhKEj0Q1LuiHd4fdDlY\n- code challenge = Base64-url-encode(SHA256(code_verifier)): p7CN1Zi4o5ARn1mYNvNFvj2r5cKkr2k6y7a573eHJXQ in the example above\n\nFor more details on PKCE see https://tools.ietf.org/html/rfc7636, appendix A has the definition of base64-url-encode\n", "operationId": "getOauthAuthorize", "parameters": [ { "name": "redirect_uri", "in": "query", "required": true, "schema": { "enum": [ "urn:ietf:wg:oauth:2.0:oob:auto" ], "type": "string" } }, { "name": "response_type", "in": "query", "required": true, "schema": { "enum": [ "code" ], "type": "string" } }, { "name": "client_id", "in": "query", "description": "the api client id supplied by Mapp Fashion", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "a randomly generated state value", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "description": "a urlsafe base64 encoded, SHA256 hash of the code verifier (a cryptographically secure randomly generated string).", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "enum": [ "S256" ], "type": "string" } } ], "responses": { "200": { "description": "Information about the authorization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationResponse" } } } }, "400": { "description": "oauth2 error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } } }, "components": { "schemas": { "AuthorizationResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "The authorization code generated", "example": "pEcnKwHD0yF3pfu1U56EBo-QbBwPMcqOYtBr5LnYTjKdNzYUGIgzied-ux-vyul7" }, "state": { "type": "string", "description": "The state parameter initially provided. You must verify the matches the initially supplied value.", "example": "a1F5Kdf5Dhn123" } }, "description": "This is an oauth2 compliant authorize endpoint (see https://tools.ietf.org/html/rfc6749) with the following limitations:\n\n- Only grant code flow is allowed\n- PKCE is mandatory i.e. you must generate a code_verifier (a randomly generated secret) and include its URL safe base64 encoded SHA256 hash as the code_challenge parameter\n- Only the S256 code challenge method is supported\n- The redirect URI must be set to urn:ietf:wg:oauth:2.0:oob:auto\n\nThis api returns a grant code that can then be exchanged for a JWT\n\nThis will create a new profile in the Mapp Fashion database and should therefore only be used if no refresh token is available.\n\ncode_challenge is constructed in the following manner:\n\n- Pick a random code_verifier value, for example 1tBnEmtSImyCykPHxHYBdzpSFhKEj0Q1LuiHd4fdDlY\n- code challenge = Base64-url-encode(SHA256(code_verifier)): p7CN1Zi4o5ARn1mYNvNFvj2r5cKkr2k6y7a573eHJXQ in the example above\n\nFor more details on PKCE see https://tools.ietf.org/html/rfc7636, appendix A has the definition of base64-url-encode\n" }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "The error code (one of the error codes defined by https://tools.ietf.org/html/rfc6749#section-4.1", "example": "invalid_request" }, "error_description": { "type": "string", "description": "A human readable description of the error" } }, "description": "Generic oauth error object" } } } } ````