Generate Authentication Token

POST /token

Try it

Parameters

X-Correlation-IDheader

Bodyapplication/x-www-form-urlencoded

client_id*client_secret*scope*grant_type*

Request sampleLanguage

curl -X POST 'https://one.ozow.com/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000' \
  -d 'client_id=asdfjasdljfasdkjf&client_secret=string&scope=payments%20refunds%20settlements&grant_type=client_credentials'

Response exampleStatus

{
  "access_token": "mF_9.B5f-4.1JqM",
  "token_type": "bearer",
  "expires_in": "3600",
  "scope": "payments"
}

Built from the response schema. Values are placeholders, not real data.

POSThttps://one.ozow.com/v1/tokenProduction

Build with AI 6 packages

A build package is every page for one task, with the API operations they use. Copy the prompt into a coding assistant, or hand it the package itself: slim links to each page, full inlines all of them in one document.

Filter

Take a paymentEverything needed to take a payment end to end with One API, from credentials through the hosted page to the webhook that confirms it, and the test cases that prove each outcome before you go live.
View package
Take a recurring paymentEverything needed to collect from a customer on a schedule with One API, from the consent the customer gives once through to each collection and the webhook that reports it.
View package
Migrate a payin from the Payments API to One APIEverything needed to move an existing redirect payin onto One API, with the legacy guide and its One API counterpart side by side.
View package

Retrieve an authentication token as per the OpenAuth 2.0 Client Credential Flow.

Authentication

This operation takes no credentials.

Header parameters

X-Correlation-ID string
Optional correlation id for the request, if not supplied a new one will be generated and passed onto all underlying requests and returned as a header.

Request body

client_id string required
The unique client id provided to the merchant during credential exchange.
client_secret string required
The secret provided to the merchant during credential exchange.
scope string required
The scope of permissions required. Can be just one or a list of space-delimited, case-sensitive strings.
grant_type string required
Must be client_credentials.

Responses

200 Succesfull response as per [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1)

X-Correlation-ID header
The correlation id for the request that was processed.

access_token string required
The access token issued by the authorization server.
token_type string required
Must be bearer as in RFC 6750.
expires_in string required
The lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
scope string
OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED.

400 Bad Request.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

A field in the request body did not validate

{
  "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83",
  "links": null,
  "code": "BadRequest",
  "title": "Bad Request",
  "detail": "amount: Amount must be greater than 0",
  "source": {
    "pointer": "/amount",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

401 Unauthorised. A scope in `scope` is not one this client is allowed. Scopes are granted per client, so a client can authenticate and still be refused a scope.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

A requested scope is not granted to this client

{
  "id": "4f7c0d2b-8a15-4e93-b06d-7c2e9f1a5b48",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Unauthorized",
  "title": "Unauthorized Request",
  "detail": "Consumer does not have access to requested scope",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": null
}

404 Not found. No client matches `client_id`, or the client has been deactivated.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

The client id does not resolve

{
  "id": "cccb6fb8-505e-4ff9-90b5-815ecf42424e",
  "links": null,
  "code": "NotFound",
  "title": "Not Found",
  "detail": "Consumer could not be found for client id YOUR_CLIENT_ID.",
  "source": {
    "pointer": "/data/clientId",
    "parameter": "/v1/token",
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

500 Internal Server Error.

X-Correlation-ID header
The correlation id for the request that was processed.

id string uuid required
a unique identifier for this particular occurrence of the problem.
links object nullable
Present on an authentication or authorisation failure, and null otherwise.
- about string uri
  A link that leads to further details about this particular occurrence of the problem. When derefenced, this URI SHOULD return a human-readable description of the error.
- type string uri
  A link that identifies the type of error that this particular error is an instance of. This URI SHOULD be dereferencable to a human-readable explanation of the general error.
code string required
An application-specific error code, expressed as a string value. Key on this rather than on title or detail, which are written for a person. A rejection at the transport level uses the status name, one of BadRequest, Unauthorized, Forbidden, NotFound, NotAllowed, Conflict, UnsupportedMediaType, BadGateway or InternalServerError. An operation refusing a request on its own rules returns a code of its own.
title string required
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
detail string required
A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
source object nullable
Where in the request the problem was found. All three keys are present whenever source is, with the ones that do not apply set to null. source itself is null where the failure is not about a part of the request.
- pointer string json-pointer nullable
  a JSON Pointer RFC6901 to the value in the request document that caused the error [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute]. This MUST point to a value in the request document that exists; if it doesn’t, the client SHOULD simply ignore the pointer.
- parameter string nullable
  A string indicating which URI query parameter caused the error.
- header string nullable
  A string indicating the name of a single request header which caused the error.
meta object nullable
A meta object containing non-standard meta-information about the error. Null where the request carried no X-Correlation-ID, and on an authentication failure, which does not echo it.
- correlationId string
  The X-Correlation-ID sent with the request, echoed back so it can be quoted to support. Absent when the request carried no correlation header.

The request failed on the Ozow side

{
  "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97",
  "links": null,
  "code": "InternalServerError",
  "title": "Internal Server Error",
  "detail": "Error occurred while processing request.",
  "source": {
    "pointer": "/data",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Guides

Request

curl -X POST 'https://one.ozow.com/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-Correlation-ID: 00000000-0000-0000-0000-000000000000' \
  -d 'client_id=asdfjasdljfasdkjf&client_secret=%3Cclient_secret%3E&scope=payments%20refunds%20settlements&grant_type=client_credentials'

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://one.ozow.com/v1/token");
request.Headers.Add("X-Correlation-ID", "00000000-0000-0000-0000-000000000000");

request.Content = new StringContent(@"client_id=asdfjasdljfasdkjf&client_secret=%3Cclient_secret%3E&scope=payments%20refunds%20settlements&grant_type=client_credentials", Encoding.UTF8, "application/x-www-form-urlencoded");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://one.ozow.com/v1/token',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/x-www-form-urlencoded',
        'X-Correlation-ID: 00000000-0000-0000-0000-000000000000',
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
client_id=asdfjasdljfasdkjf&client_secret=%3Cclient_secret%3E&scope=payments%20refunds%20settlements&grant_type=client_credentials
JSON,
]);

$response = curl_exec($curl);
curl_close($curl);

const response = await fetch("https://one.ozow.com/v1/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
  },
  body: `client_id=asdfjasdljfasdkjf&client_secret=%3Cclient_secret%3E&scope=payments%20refunds%20settlements&grant_type=client_credentials`,
});

const data = await response.json();

import requests

headers = {
    "Content-Type": "application/x-www-form-urlencoded",
    "X-Correlation-ID": "00000000-0000-0000-0000-000000000000",
}

payload = """client_id=asdfjasdljfasdkjf&client_secret=%3Cclient_secret%3E&scope=payments%20refunds%20settlements&grant_type=client_credentials"""

response = requests.post(
    "https://one.ozow.com/v1/token",
    headers=headers,
    data=payload,
)

Response

Succesfull response as per [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1)

{
  "access_token": "mF_9.B5f-4.1JqM",
  "token_type": "bearer",
  "expires_in": "3600",
  "scope": "payments"
}

Built from the response schema. Values are placeholders, not real data.

Bad Request.

{
  "id": "3a6c9e01-5f2b-4d8a-9c47-1e0b7d5a2f83",
  "links": null,
  "code": "BadRequest",
  "title": "Bad Request",
  "detail": "amount: Amount must be greater than 0",
  "source": {
    "pointer": "/amount",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Unauthorised. A scope in `scope` is not one this client is allowed. Scopes are granted per client, so a client can authenticate and still be refused a scope.

{
  "id": "4f7c0d2b-8a15-4e93-b06d-7c2e9f1a5b48",
  "links": {
    "about": "https://ozow.stoplight.io/docs/one-api/zi18vomr0jm8c-generate-authentication-token",
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1"
  },
  "code": "Unauthorized",
  "title": "Unauthorized Request",
  "detail": "Consumer does not have access to requested scope",
  "source": {
    "pointer": null,
    "parameter": null,
    "header": "Authorization"
  },
  "meta": null
}

Not found. No client matches `client_id`, or the client has been deactivated.

{
  "id": "cccb6fb8-505e-4ff9-90b5-815ecf42424e",
  "links": null,
  "code": "NotFound",
  "title": "Not Found",
  "detail": "Consumer could not be found for client id YOUR_CLIENT_ID.",
  "source": {
    "pointer": "/data/clientId",
    "parameter": "/v1/token",
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Internal Server Error.

{
  "id": "9e0d5a83-6b24-4c19-8f7a-2d1b3e6c0a97",
  "links": null,
  "code": "InternalServerError",
  "title": "Internal Server Error",
  "detail": "Error occurred while processing request.",
  "source": {
    "pointer": "/data",
    "parameter": null,
    "header": null
  },
  "meta": {
    "correlationId": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}