# We're here to help

Need assistance or more information for your API needs? We are here to help and provide answers to your questions. Reach out to our support team.

## FAQ

Need help? check out our FAQ, documentation.

### How do I access fileactive APIs?

Contact your ANZ account manager to discuss requirements and arrange for access. A technical consultant will be assigned to provide advice and assitance throughout the process.

### Are fileactive APIs subject to rate limits or throttling?

By default the following rate limits are applied:

| Type                        | TPH (Transactions Per Hour) | TPM (Transactions Per Minute) | TPS (Transactions Per Second) |
| --------------------------- | --------------------------- | ----------------------------- | ----------------------------- |
| Authorization               | 10                          | n/a                           | 2                             |
| NPP Single Payment          | n/a                         | 30                            | 2                             |
| Payments                    | n/a                         | 30                            | 2                             |
| Payment Inquiry             | n/a                         | 90                            | 2                             |
| Statement / BTR             | 25                          | n/a                           | n/a                           |
| FX RFQ                      | 500                         | n/a                           | 10                            |
| PayTo Create Mandate        | n/a                         | n/a                           | 10                            |
| PayTo Change Mandate Status | n/a                         | n/a                           | 10                            |
| PayTo Get Mandate Details   | n/a                         | n/a                           | 5                             |
| PayTo Create MPIR           | n/a                         | n/a                           | 5                             |
| PayToQuery Resolution       | n/a                         | n/a                           | 5                             |

Non-default limits will be considered on request. Please discuss with your ANZ account or relationship manager to request a non-default limit. Temporary limits may also be requested for specific ad hoc use cases.

### Which rate limiting algorithms do you use?

For most use cases one of two algorithms is implemented for rate limiting:

#### Fixed Window

- The system uses a window size of n seconds (e.g., 60 or 3600 seconds) to track the fixed window algorithm rate.
- Each incoming request increments the counter for the window. It discards the request if the counter exceeds a threshold.
- The current timestamp floor typically defines the windows, so 12:00:03, with a 60-second window length, would be in the 12:00:00 window.

#### Sliding Window

Sliding Window is a hybrid approach. Like the fixed window algorithm, we track a counter for each fixed window. Next, we account for a weighted value of the previous window's request rate based on the current timestamp to smooth out bursts of traffic.

#### Sliding Window Example:

- Given a limit of 100 transactions per hour.
- **Window 1 (13:00 - 14:00):**
  - Between 13:00 - 14:00, 80 requests are received. This is within the 100 tph limit so all are allowed.
- **Window 2 (14:00 - 15:00):**
  - By **14:15**, 20 requests are received. This is 25% (15 minutes) in to window 2, so weighted average would include 75% from the previous window. Request rate: 20 (all requests within window 2) + 60 (75% of requests from window 1) = 80 requests. Request rate is still within the 100 tph maximum.
  - By **14:30**, 75 requests have been received. This is 50% (30 minutes) in to window 2, so weighted average would include 50% from the previous window. Request rate is: 75 (all requests within window 2) + 40 (50% weighted average from previous window) = 115 requests. This exceeds the 100 tph limit so further requests would return an HTTP 429 (Too Many Requests) status code until the weighted request rate is below the agreed limit.
  - By **14:45**, no further requests have been made. This is 75% (45 minutes) through window 2. Request rate is 75 (current window) + 20 (25% weighted average from previous window) = 95 requests. As this is below the 100 tph limit further requests will be accepted.

### Where are changes to the site and specifications documented?

Significant changes to the site and documentation will be listed in the [Change Log](/support/ChangeLog).

### What is OAuth 2.0?

OAuth 2.0 supported APIs are tagged with `X-RequestKey`. Detailed information can be found on the [RFC 6749 OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) page.

ANZ's OAuth 2.0 API is used for authentication and authorization and is OpenID Connect compliant, requesting a token involves calling the ANZ token issuer endpoint with a valid `client credential grant`. ANZ will issue a reference token that can be used for subsequent calls to ANZ for the lifetime of the token.

> A Client Credential Grant is required to obtain an access token. The customers public key must be pre-exchanged for ANZ to verify the signed Client Credential Grant.

### What is client credential grant?

Client credentials are used to authenticate and authorize applications rather than users. In the OAuth 2.0 framework, client credentials grant type is used when applications request an access token to access their own resources, not on behalf of a user.

### What is a JWT?

A [JSON Web Token](https://jwt.io/) or JWT, pronouced jot is an internet standard RFC 7519 used to transfer claims from a server to a client in a secured and URL-safe means. Clients are then authorised to access claims as specified in the scope specified by the client in the `Client Credential Grant Request`.

### How to construct a valid JWT?

Refer to [jwt.io](https://jwt.io/) for detailed information.

JWT consists of three parts:

- Header
- Payload
- Signature

The three parts are encoded using `Base64url Encoding` and concatenated. Each part is seperated using a period.

JWT = header.payload.signature

#### Header

| Field | Name      | Description                                    | Value   |
| ----- | --------- | ---------------------------------------------- | ------- |
| alg   | algorithm | Identifies the algorithm used in the signature | `RS256` |
| typ   | JWT       | Identifies the token type                      | `jwt`   |

#### Payload

| Field | Name       | Description                                                                             | Value                                         | Example                                     |
| ----- | ---------- | --------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- |
| sub   | subscriber | ANZ provided Customer Code, ALL CAPS                                                    | PROVIDED VALUE                                | CUSTOMERCODE                                |
| exp   | JWT expiry | Set the time, using UNIX EPOCH, after which the token cannot be accepted for processing | GENERATED EPOCH VALUE                         | 1662530902                                  |
| aud   | audience   | Provides an identification of the intended recipient. Token cannot be processed         | `https://api.fileactive.uat.anzgcis.com/auth` | https://api.fileactive.uat.anzgcis.com/auth |

#### Signature

JWT signatures are used to generate a Message Authentication Code (MAC) to verify that the message is correct and true. ANZ verifies the signature of a JWT using a public key as provided by the customer. Customers must generate the signature/MAC value using the corresponding Private Key.

#### Example JWT

Example JWT with signed and encoded content:

```
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.ewoJInN1YiI6ICJDVVNUT01FUkNPREUiLAogICJleHAiOiAiMTY2MjUzMDkwMiIsCiAgImF1ZCI6ICJodHRwczovL2FwaS5maWxlYWN0aXZlLnVhdC5hbnpnY2lzLmNvbS9hdXRoIgp9.ewWggi_ti3LyCc_X84XbeHDh1GU-J2uVx-vC_jZN2ZnO_CjwrUlAC3LXwEh2DX6IPTeP2jpX1IdWt-IaQlzendnfBYmq7YqxAWKhJiZATNM15YxSqQH67Z3Ic3UscXNMvRPClnfHBuIfalSnBAVOzm-WhQ9gboEpSGJ9-wQB7qN5pBXR4IiWUy6NX2wWLXGdLnQozg_A1nTp0Wwr_xQO4_qcIAUnAxG7SaJ1zlOq_QLMMdvczgHt1_DCTnIYetH5Wy4Y47Jyb0GrzfcTjcIR1z6jS-e4gcMyom6hOO-QH5vWFW3t5hhCaM8la7o8LhEhYzXoXXUYCO7Q7qfMK-vBVg
```

### What is a bearer token?

Bearer tokens are generated by and returned to a customer during a Client Credential Interaction. Customer must provide a valid JWT with an `exp` field that dates not more than 60 minutes into the future. Bearer Tokens are GUIDs, 32 character hypenated strings.

### How are scopes used?

A scope is a mechanism in OAuth 2.0 to define what an application can access (such as payments) and whether the access is read or write. An application can request one or more scopes during a credential grant request. The `bearer token` issued will be limited to the scopes granted.

```
---
```

### How are payloads secured?

#### JOSE(JWT)

Payload data is secured using a combination of JSON Web Signature (JWS) & JSON Web Encryption (JWE)

Sequence to create a valid `secured_payload` object:

1. Create valid JSON payload
2. Sign JSON object using JWS
3. Encrypt payload using JWE
4. Encapsulate signed and encrypted payload in `secured_payload` object

#### JSON Web Signature (JWS)

| Algorithm | Supported Key Size |
| --------- | ------------------ |
| RS256     | 2048 or 4096       |

#### JSON Web Encryption (JWE)

| Algorithm | Encryption    | Key Size |
| --------- | ------------- | -------- |
| RSA-OAEP  | A256CBC-HS512 | 2048     |

### What is X-RequestKey used for?

ANZ Support requires the `X-RequestKey` value when engaged, the `X-RequestKey` is a GUID assigned to each request sent to ANZ for processing. ANZ applications are developed to retain context and information on the `X-RequestKey` value, providing the `X-RequestKey` will allow ANZ Support to uniquely identify the API call in question.

## Support

### Need help or have questions?

If you have any questions, concerns, or require assistance while using the Fileactive APIs, we're here to help. For personalised support tailored to your business needs, please reach out to your dedicated relationship management team.

Your relationship team can assist with:

- **Account and API access:** Ensuring your account is set up correctly and that you have the appropriate access to the APIs.
- **API integration:** Guidance on integrating the Fileactive APIs into your systems and workflows.
- **Technical support:** Help troubleshooting issues or understanding API functionality.
- **Business consultation:** Discussing how our APIs can help achieve your business objectives and exploring additional solutions.
- **Further information:** Providing detailed documentation, use case examples, or assisting with any other queries you may have.

By working closely with your relationship team, you can get the most out of our products and services, ensuring a smooth and successful experience.

For immediate help, don't hesitate to contact your relationship team directly. We're here to ensure you get the support you need at every step of your journey with Fileactive APIs.
