How to Fix Common RukkyHub API Authentication Errors

How to Fix Common RukkyHub API Authentication Errors

If your RukkyHub API request returns an authentication error, the problem may be related to your API key, key permissions, account status, or security restrictions. This guide explains how to identify common errors and troubleshoot them safely.

1. Check That Your API Key Is Correct

RukkyHub API requests require a valid API key. If your request returns an error such as “Invalid api key”, check the following:

• Confirm that you copied the correct API key from your RukkyHub Developer Portal.
• Check that the key has not been revoked or replaced.
• Remove accidental spaces or line breaks from the key.
• Make sure you are using the appropriate key for your intended environment.

Live API keys commonly begin with rk_live_. Test keys use the rk_test_ prefix. Keep your key private and never publish it in frontend JavaScript or public website code.

2. Fix “The api key field is required”

This error means the API request did not include the required API credential in a recognized location.

The recommended method is to send your key in the X-API-KEY HTTP header. For example:

curl -X POST https://developers.rukkyhub.com/api/v1 \  -H "X-API-KEY: YOUR_API_KEY" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d "action=balance"

Replace YOUR_API_KEY with your actual key in your private server environment. Do not paste a real key into public documentation, screenshots, or support messages.

The API also documents a body parameter named key as an alternative. Use the header method where possible.

3. Fix “This API key is not allowed for this action”

API keys can be restricted to specific scopes. A key may authenticate successfully but still be blocked from performing an action that its permissions do not allow.

To resolve this issue:

1. Open your RukkyHub dashboard and go to the Developer Portal.
2. Open the API Keys section.
3. Review the scopes assigned to the key you are using.
4. If necessary, create a key with the scope required for your intended API action.
5. Update your private server configuration to use the appropriate key.

For example, listing SMM services requires the services scope, while placing an SMM order requires the add scope. Other actions may require scopes such as balance, status, or the relevant VTU or gift card permission.

4. Fix “Invalid action”

This error usually means that the value supplied in the action parameter is not recognized.

Check that:

• Your request includes the required action parameter.
• The action name matches the official API reference exactly.
• You have not misspelled the action or added unintended spaces.
• You are using the correct action for the service you want to access.

For example, a balance request uses action=balance, while a request to list SMM services uses action=services.

5. Fix API Domain or IP Whitelist Errors

RukkyHub API keys can have security restrictions based on approved IP addresses or domains. If your key uses a whitelist, a request from an unapproved source may be rejected.

If you see an error such as “API key is restricted to whitelisted domains.” or “This check needs an Origin (browser) or X-API-ORIGIN header”, review the API key's security settings.

• Confirm that your website domain or server IP is included in the applicable whitelist.
• For browser-origin checks, verify that the request is sent from the approved domain.
• For server-to-server requests, follow the developer documentation for the required origin header or configured IP restrictions.
• When domain whitelisting requires it, send the approved origin using X-API-ORIGIN or the documented origin or domain body parameter.

Do not disable security restrictions without understanding the consequences. If your integration uses a server, configure it to comply with the whitelist requirements rather than exposing your API key in browser code.

6. Fix API Access or Account Disabled Errors

If the response indicates that your API credential or account is disabled, the issue may not be fixable by changing your request parameters.

• Confirm that your API access plan has been purchased and approved where required.
• Check whether your account or API access is currently restricted.
• If the error persists, contact RukkyHub support and provide the exact error message, the affected action, and the approximate time of the request.

Never send your complete API key or account PIN in a support message.

7. Fix “VTU API access is not enabled for your plan”

This message indicates that the current API plan does not include the requested VTU capability.

Review your API plan and confirm that it supports the VTU action you are attempting to use. If it does not, follow the Developer Portal's instructions for obtaining a plan that includes the required access.

8. Fix “SMM API access is not enabled for your plan”

This error indicates that your current API plan does not include SMM API access. Review your plan details and upgrade or request the appropriate access if necessary.

Remember that a valid API key alone does not guarantee access to every API feature. Your plan and the key's assigned scopes must also permit the requested action.

9. Check Your API Request Format

RukkyHub API requests use the following base URL:

https://developers.rukkyhub.com/api/v1

Requests should use the POST method, send form-encoded parameters with the application/x-www-form-urlencoded content type, and process the JSON response.

A basic request should include the required authentication credential and an appropriate action parameter. If authentication appears correct but the request still fails, compare the request format and parameters with the official API reference.

10. Keep Your API Key Secure

• Store API keys in server-side environment variables or an appropriate secrets manager.
• Never expose secret keys in frontend JavaScript, public repositories, or client-side application bundles.
• Grant only the scopes your integration needs.
• Use HTTPS for API requests.
• If a key is exposed or compromised, revoke it and create a replacement key.

Official RukkyHub API Resources

• API Authentication Guide — API keys, scopes, and security restrictions.
• API Error Codes — documented error messages and explanations.
• Getting Started — base URL and request format.
• API Reference — supported actions and required parameters.

Frequently Asked Questions

Why does my API key work for one action but not another?

Your key may not have the scope required for the second action, or your API plan may not include that feature. Check both the key permissions and your plan.

Can I put my API key in my website's frontend code?

No. Keep secret API keys on your backend server. Public frontend code can expose the key to other people.

What should I do if I have checked everything and authentication still fails?

Review the official authentication and error-code documentation, verify the exact request being sent, and contact RukkyHub support with the error message and relevant non-sensitive request details. Never include your full API key or PIN.