Skip to content

Commit

Permalink
Merge pull request #786 from centrapay/add-auth-page
Browse files Browse the repository at this point in the history 
♻️ Migrate Auth API reference guide
  • Loading branch information
@MeganSteenkamp
MeganSteenkamp authored Oct 4, 2023
2 parents 3681922 + e5e0f0a commit 4a74002
Show file tree
Hide file tree
Showing 3 changed files with 189 additions and 5 deletions.
186 changes: 186 additions & 0 deletions src/content/api/auth.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
---
title: Auth
description: Introduction to Authentication
draft: true
nav:
path: API
order: 2
---

## Authenticating API Calls

API calls can be authenticated by either providing an API key in the
"X-Api-Key" header or by providing a user access token in the "Authorization"
header.

Org [Accounts](https://docs.centrapay.com/api/accounts) accessed with a user access token require the
"X-Centrapay-Account" header to be provided. The "X-Centrapay-Account" header
specifies the unique identifier of the Centrapay Org Account.

### Authenticate with API key

```bash [Request]
curl -X GET https://service.centrapay.com/api/account-memberships \
-H "X-Api-Key: $api_key"
```

### Authenticate with user access token

```bash [Request]
curl -X GET https://service.centrapay.com/api/account-memberships \
-H "Authorization: $jwt"
```

### Authenticate org account with user access token

```bash [Request]
curl -X GET https://service.centrapay.com/api/account-memberships \
-H "Authorization: $jwt" \
-H "X-Centrapay-Account: Jaim1Cu1Q55uooxSens6yk"
```

## API Keys

[API Keys](https://docs.centrapay.com/api/api-keys) provide enduring access to a single Centrapay account.

The Centrapay test merchant API key is available to test creating payment requests:
`f32c5497297084e5354b47c40d5ccacb109ce483`.

## User Access Tokens

User access tokens provide time-limited access to all Centrapay accounts for
which the user is a member. Access tokens are issued using OIDC code flow via
the Centrapay OAuth authorization server and login page at auth.centrapay.com.

After successfully negotiating the OIDC code flow your application will have access to three tokens:

| Token | Description |
| ------------- | --------------------------------------------------------------------- |
| Id Token | JWT containing user attributes such as id, phone and email. |
| Access Token | JWT granting access to Centrapay APIs. Expires after 1 hour. |
| Refresh Token | Token for OIDC token exchange. Expires after 60 days or when revoked. |

A good starting point for learning more about OIDC is Okta's [OAuth OIDC Illustrated Guide](https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc).

When initiating a login request, a valid redirect URI must be provided. To
obtain a dedicated OAuth client id with your application's redirect URI(s)
whitelisted please contact Centrapay support. Your callback URI can be for a
website (such as "https://yourapp.example.com/oidc-callback") or mobile app
(such as "com.example.yourapp://oidc-callback").

Your application can use any OIDC client to negotiate the authentication flow
but it must support OIDC authorization code flow with [PKCE](https://oauth.net/2/pkce/).
See the [Example OIDC Consumer](/guides/example-oidc-consumer) guide for a
working example using the "oidc-client" JavaScript library. The Centrapay
authorization server configuration can be interrogated via
`https://auth.centrapay.com/.well-known/openid-configuration`.

When handling the OIDC callback, browser based applications should slurp the
callback parameters by performing a `location.replace()` so they are not
available in the browser's location bar or browsing history. If your application
needs to talk directly to service.centrapay.com from a browser then it will
also need to be whitelisted for cross-origin requests.

### Claims

The following table lists the claims which may be be included in a user id token.
At minimum, the "sub" claim and one of "phone_number" or "email" will be present.

| Name | Description |
|:----------------------|:------------------------------------------------------------------|
| sub | Centrapay user id |
| email | email address |
| phone_number | phone number |
| given_name | given name(s) |
| family_name | surname |
| preferred_username | Centrapay user handle |
| phone_number_verified | phone number has been verified (can be used for account recovery) |
| email_verified | email has been verified (can be used for account recovery) |

## Roles and Permissions

Users and API keys are assigned a role for their associated Centrapay
account(s). The permissions granted to the roles are shown in the table below.

Most permissions apply only to resources owned by the associated account. Some
permissions, such as payment-requests:pay, apply globally to all resources
regardless of the account the resource belongs to. The global permissions are
indicated below with a star (✸).

### Account Flags

Some permissions require an additional flag associated to their individual account or the
targeted account that owns the resource (they may be the same account). For each permission,
if there is a flag associated to it then at least one of them must be met.

| Symbol | Description |
| ------ | ------------------------------------------------------------------------------------------------ |
| 👤 | A trusted user flag on the individual account, obtained by verifying a NZ phone number. |
| 🧀 | An external-asset-issuer subscription on the targeted Account, obtained by contacting centrapay. |
| 🗄 | The targeted account must be of type org. |
| 🪙 | A collection-manager subscription on the targeted Account, obtained by contacting centrapay. |

### Permissions

| Permission | Account Owner | Anon Consumer | Merchant Terminal | External Asset Provider | Cashier |
| ---------------------------------- | ------------- | ------------- | ----------------- | ----------------------- | ------- |
| accounts:create | ✅ | | | | |
| accounts:read | ✅ | | | ✅ | ✅ |
| accounts:updat | ✅ | | | | |
| api-keys:create | ✅ | | | | |
| api-keys:list | ✅ | | | | |
| api-keys:update | ✅ | | | | |
| asset-transfers:claim | ✅ | | | ✅ | |
| asset-transfers:create 👤 🧀 | ✅ | | | ✅ | |
| asset-transfers:read | ✅ | | | ✅ | |
| assets:read | ✅ | | | ✅ | |
| assets:spend 👤 | ✅ | | | | |
| bank-account-approvals:create | ✅ | | | | |
| bank-account-requests:authorize | ✅ | | | | |
| bank-account-requests:create | ✅ | | | | |
| bank-accounts:create | ✅ | | | | |
| bank-accounts:read | ✅ | | | | |
| business:create | ✅ | | | | |
| business:update | ✅ | | | | |
| business:read | ✅ | | | | |
| collections:create 🪙 | ✅ | | | | |
| collections:read 🪙 | ✅ | | | | |
| external-assets:create 👤 🧀 | ✅ | | | ✅ | |
| external-assets:update | ✅ | | | ✅ | |
| integration-requests:configure | | | | | |
| integration-requests:create 🗄 | ✅ | | | | |
| integration-requests:read 🗄 | ✅ | | | | |
| invitations:accept | ✅ ✸ | | | | |
| invitations:read | ✅ ✸ | | | | |
| media-uploads:create | ✅ | | | | |
| memberships:delete 🗄 | ✅ | | | | |
| memberships:update | ✅ | | | | |
| merchants:create 🗄 | ✅ | | | | |
| merchants:list 🗄 | ✅ | | | | ✅ |
| merchants:read 🗄 | ✅ | | | | ✅ |
| merchants:update 🗄 | ✅ | | | | |
| patron-codes:create | ✅ | | | | |
| patron-codes:read | ✅ | | ✅ | | ✅ |
| payment-activities:read | ✅ | | ✅ | | ✅ |
| payment-conditions:approve | ✅ | | ✅ | | ✅ |
| payment-requests:cancel 🗄 | ✅ | | ✅ | | ✅ |
| payment-requests:create 🗄 | ✅ | | ✅ ✸ | | ✅ |
| payment-requests:pay 🗄 | ✅ ✸ | ✅ ✸ | ✅ | | ✅ ✸ |
| payment-requests:read | ✅ ✸ | ✅ ✸ | ✅ ✸ | | ✅ ✸ |
| payment-requests:read-by-shortcode | ✅ | | ✅ | | ✅ |
| payment-requests:refund 🗄 | ✅ | | ✅ | | ✅ |
| payment-requests:void 🗄 | ✅ | | ✅ | | ✅ |
| payment-requests:release 🗄 | ✅ | | ✅ | | ✅ |
| payment-requests:confirm 🗄 | ✅ | | ✅ | | ✅ |
| quotas:read | ✅ | | | | |
| quotas:read | ✅ | | | | |
| redemption-conditions:create 🪙 | ✅ | | | | |
| scanned-code:decode | ✅ | | ✅ | | ✅ |
| tokens:create 🪙 | ✅ | | | | |
| topups:create 👤 | ✅ | | | | |
| topups:read | ✅ | | | | |
| wallets:create | ✅ | | | | |
| wallets:deposit | ✅ | | | | |
| wallets:read | ✅ | | | | |
| wallets:transfer 👤 | ✅ | | | | |
| wallets:withdraw | ✅ | | | | |
5 changes: 3 additions & 2 deletions src/content/api/introduction.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
---
title: API Introduction
title: Introduction
description: Introduction to the API Reference
draft: true
nav:
path: API/Getting Started
path: API
order: 1
---

Expand Down
3 changes: 0 additions & 3 deletions src/navigation/sideNavConfig.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,5 @@ export default [
title: 'API',
subTitle: 'For developers',
icon: 'Settings',
children: [
{ title: 'Getting Started' },
]
},
];

0 comments on commit 4a74002

Please sign in to comment.