Glue API: Authenticate as a merchant user

This endpoint allows authenticating as a merchant user. A merchant user is a Back Office user that is assigned to a merchant; the access token it receives carries the merchant-user scope, which the Backend API maps to the ROLE_MERCHANT_USER role. Resources built for the Merchant Portal audience, like the merchant profile, check for this role.

The merchant does not have to be approved: a merchant user of a merchant that is still waiting for approval can authenticate and use the endpoints available to merchant users.

Installation

The endpoint is provided by the OauthBackendApi module; to install it, see Integrate the authentication. The merchant-user scope is provided by the OauthMerchantUser module; to register its plugins, see Optional: Enable merchant user authentication.

Authenticate as a merchant user

POST /token

Request

Request sample: authenticate as a merchant user

POST https://glue-backend.mysprykershop.com/token

{
    "data": {
        "type": "tokens",
        "attributes": {
            "username": "[email protected]",
            "password": "change123"
        }
    }
}

Response

{
    "data": {
        "type": "tokens",
        "id": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
        "attributes": {
            "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
            "tokenType": "Bearer",
            "expiresIn": 28800,
            "refreshToken": "def50200a1b2c3d4e5f6789012345678901234567890abcdef..."
        }
    }
}

Refresh the access token

To exchange a refresh token for a new access token and refresh token, send the request:

POST /refresh-tokens

Request sample: refresh the access token

POST https://glue-backend.mysprykershop.com/refresh-tokens

{
    "data": {
        "type": "refresh-tokens",
        "attributes": {
            "refreshToken": "def50200a1b2c3d4e5f6789012345678901234567890abcdef..."
        }
    }
}

{
    "data": {
        "type": "refresh-tokens",
        "id": "def50200f1e2d3c4b5a6978012345678901234567890fedcba...",
        "attributes": {
            "refreshToken": "def50200f1e2d3c4b5a6978012345678901234567890fedcba...",
            "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
            "tokenType": "Bearer",
            "expiresIn": 28800
        }
    }
}

Roles the token grants

The scopes in the token decide which roles the Backend API grants to the request:

ROLE_USER is held by every authenticated caller, so a resource that must distinguish the two audiences checks ROLE_MERCHANT_USER or ROLE_BACK_OFFICE_USER. A merchant user calling a resource that requires ROLE_BACK_OFFICE_USER gets 403, and the other way round.

On every request with a valid token, the Backend API resolves the user behind the token and makes it the acting user. The user must be active; a token of a deactivated or deleted user is rejected with 401 and the error code 003. For details, see API Platform security. To restrict merchant users to the data of their merchant, see Integrate Persistent ACL for merchant API endpoints.

Possible errors

Failed requests return a JSON:API error document. The code of an authentication failure is the error type reported by the OAuth server that issues the tokens; the same OAuth server serves the Back Office, the Merchant Portal, and the legacy form-encoded POST /token request.

{
    "errors": [
        {
            "code": "invalid_grant",
            "status": 401,
            "detail": "The user credentials were incorrect.",
            "message": "The user credentials were incorrect."
        }
    ]
}

To view generic errors and status codes of the Backend API, see Backend API request and response reference.